1. ChannelEngine Help Center
  2. APIs
  3. Merchant API

Articles in this section

See more

Merchant API: customer details and addresses on orders

  • Created
  • Updated

About this article

This article explains how to retrieve customer details and addresses from order responses via the Merchant API, how to handle the two supported address formats, and how to identify and process pickup point and packstation deliveries.

Table of contents

Introduction

Retrieve orders

Address fields (BillingAddress and ShippingAddress)

Billing address vs. shipping address

Line1/Line2/Line3 vs. split address fields

Recognizing pickup points and packstations

Introduction

When you retrieve orders via GET /v2/orders or GET /v2/orders/new, each order response includes customer details and two address objects: a billing address for invoicing and VAT purposes, and a shipping address for delivery. These two addresses frequently differ — for example, in business orders or gift purchases — so always read them from their respective fields rather than assuming they match.

Address data in ChannelEngine comes in two formats depending on whether address validation is enabled for the channel. Structured European addresses are split into separate fields (StreetName, HouseNr, HouseNrAddition), while unstructured addresses use free-text lines (Line1, Line2, Line3). Channels in the Asia-Pacific region always use the line format, regardless of validation settings.

In some cases, the shipping address does not reflect a customer's home or business address at all — when a customer selects a pickup point or packstation at checkout, the shipping address is replaced by the location of that collection point. This article covers how to detect these cases using the AddressType field and how to extract the additional identifiers required by carrier APIs.

Retrieve orders

Inspect the responses of your orders to find your customers' details and addresses.

  • Retrieve orders: GET /v2/orders
    Returns a paginated list of orders matching your filters. Use this endpoint when you need fine-grained control — for example, filtering by status, date range, channel, or acknowledgement state.
  • Retrieve new orders: GET /v2/orders/new
    Returns only orders with status NEW that have not yet been acknowledged. The recommended starting point for most polling-based integrations.

Customer details

Field Type Description
Email string The customer's email address.
Phone string The customer's telephone number.
LanguageCode string The language of the order as a 2-letter ISO 639-1 code (for example, nl, de, en).
CompanyRegistrationNo string The company's chamber of commerce number, if provided. Typically populated for B2B orders.
VatNo string The company's VAT number, if provided. Typically populated for EU B2B orders where the buyer is VAT-registered.
PaymentMethod string The payment method used for this order (for example, iDEAL, creditcard).
PaymentReferenceNo string The reference or transaction ID for the payment.
CurrencyCode string The ISO 4217 currency code for the original order amounts (the currency the customer paid in).
ExtraData object Channel-specific additional data on the order, as key-value pairs. Contents are dynamic and differ per marketplace — see Merchant API: interpreting order lines and extra data for examples and guidance on how to handle this field.

Address fields (BillingAddress and ShippingAddress)

Both BillingAddress and ShippingAddress use the same structure. ChannelEngine supports two address formats depending on whether address validation is enabled on the channel: a split format (street name, house number, and addition as separate fields) and an unstructured format (free-text lines). Check which fields are populated before processing.

Field Type Description
FirstName string The customer's first name.
LastName string The customer's last name, including surname prefix (for example, van, de, du).
Gender enum The salutation/gender of the addressee, where provided by the channel. Values: MALE, FEMALE, NOT_APPLICABLE. Not all channels provide this field. Use it only for salutation purposes where relevant — do not use it to gate logic.
CompanyName string Company name, if the order is addressed to a business.
AddressType enum The type of address: HOME, PACKSTATION, or PICKUP_POINT.
StreetName string Street name without house number information. Populated when address validation is enabled in ChannelEngine. May be empty if Line1 / Line2 is used instead.
HouseNr string House number. Populated when address validation is enabled. May be empty if Line1 / Line2 is used.
HouseNrAddition string House number addition, if applicable. For example, for the address Groenhazengracht 2c: StreetName = Groenhazengracht, HouseNr = 2, HouseNrAddition = c.
Line1 string The first address line. Use this field when address validation is disabled in ChannelEngine.
Line2 string The second address line. Use when address validation is disabled.
Line3 string The third address line. Use when address validation is disabled.
ZipCode string Postal or ZIP code.
City string City name.
Region string State, province, or region. Optional.
CountryIso string Two-letter ISO 3166-1 alpha-2 country code (for example, NL, BE, FR).
Original string The full address as a single unstructured string. Populated when the address was entered as free text and later parsed into structured fields.
PickupPointName string Name of the pickup point, when AddressType is PICKUP_POINT or PACKSTATION.
PickupPointNumber string Number of the pickup point, when AddressType is PICKUP_POINT or PACKSTATION.
NB: when building your address formatting logic, check StreetName first. If it is populated, use the split fields (StreetName, HouseNr, HouseNrAddition). If it is empty, fall back to Line1 / Line2 / Line3. Do not rely on only one format being present — this varies per channel.

Billing address vs. shipping address

Every order carries two address objects that serve different purposes:

  • BillingAddress — the invoice address. This is the address associated with the customer's payment method and is used for VAT and invoicing purposes. It is not necessarily the address where the goods are delivered.
  • ShippingAddress — the delivery address. This is where the goods should be sent. Always use this address when creating a shipment or printing a shipping label.

In many consumer orders these two addresses are identical, but for business orders or gift purchases they frequently differ. Never assume they match — always read them from their respective fields.

Line1/Line2/Line3 vs. split address fields

ChannelEngine supports two address formats in the same response object, depending on whether address validation is enabled for the channel:

  • Split format — StreetName, HouseNr, and HouseNrAddition are populated as separate fields. This is the preferred format for most European channels where addresses follow a structured pattern. Use these fields when building shipment labels or passing addresses to carrier APIs that require structured input.
  • Unstructured format — Line1, Line2, and Line3 are populated as free-text lines. This occurs when address validation is disabled on the channel, or when the channel itself does not provide structured address data.
NB: for channels operating in the Asia-Pacific region (Japan, South Korea, Southeast Asia, Australia, and others), always read Line1, Line2, and Line3 rather than the split fields. Address formats in this region frequently deviate from Western conventions — for example, addresses may be written in a different order (largest unit first), or the field may contain a delivery instruction rather than a postal address at all (for example, "Leave at reception — Building B"). Attempting to parse APAC addresses using the split fields will produce incorrect or empty results.
NB: a reliable way to handle both formats in a single integration: check whether StreetName is populated. If it is, use the split fields. If it is empty, fall back to Line1 / Line2 / Line3. Log any case where neither set of fields is populated — this indicates a data quality issue on the channel side.

Recognizing pickup points and packstations

When a customer chooses to collect their order from a pickup point or a packstation (an automated parcel locker, as used by DHL in Germany), the ShippingAddress reflects the location of that point rather than the customer's home address. You can detect this using the AddressType field:

  • PICKUP_POINT — the delivery address is a staffed pickup location (for example, a shop or post office acting as a collection point).
  • PACKSTATION — the delivery address is an automated parcel locker.
  • HOME — standard home or business delivery.

For pickup point and packstation deliveries, also read the PickupPointName and PickupPointNumber fields — these contain the name and identifier of the specific location, which are required by most carrier APIs to route the shipment correctly.

Example — packstation shipping address: AddressType: PACKSTATION · PickupPointName: DHL Packstation 142 · PickupPointNumber: 142

NB: for packstation deliveries, the customer's DHL Postnummer (personal identifier) is typically included in the address data provided by the channel — often in Line2 or as an ExtraData value on the order. Check the channel-specific documentation for where this appears.

 

Related articles

Comments

0 comments

Article is closed for comments.