2025-10-30: Cart Service - address management

Overview

Cart Service now supports comprehensive address management directly on the cart object. This enhancement allows you to specify billing and shipping addresses that are used for tax determination and shipping cost calculation.

New attribute added to cart:

addresses - an array of addresses associated with the cart

Each address can include the following properties:

type - address type: BILLING or SHIPPING
contactName - contact name for the address
companyName - company name
street - street name
streetNumber - street number
streetAppendix - additional street information
zipCode - postal/zip code
city - city name
country - two-letter country code (ISO 3166)

Address auto-population

When addresses are not explicitly provided in the request, the Cart Service automatically populates them based on the following priority order:

Legal Entity Address - If the cart is associated with a legal entity, the first location with both country,zip-code and required address type is used (origin: LEGAL_ENTITY).
Customer Address - If the cart has a logged-in customer, the default address matching the required type is used (origin: CUSTOMER).
Site Homebase Address - If neither of the above is available, the site's homebase address is used (origin: SITE).

Addresses provided in the request are marked with origin REQUEST in the response.

For backward compatibility the legal entity address population has to be enabled in the tenant settings: enableLegalEntityAddressFallbackInCart. It is enabled by default for all new tenants.

Address usage

The addresses specified on the cart are used for:

Tax determination - The appropriate tax country is determined based on the billing or shipping address, as configured in the site's taxDeterminationBasedOn setting.
Shipping cost calculation - The shipping address is used to calculate accurate shipping costs based on the destination.

For more details, see:

Backward compatibility

The existing countryCode and zipCode parameters at the cart level are still supported for backward compatibility. However, the new addresses array provides a more comprehensive and flexible approach to address management.