This feature is only available for stores using B2B Buyer Portal, which is currently available to selected accounts.

The B2B Addresses API allows you to provision and maintain the shipping and billing destinations used by buyer organizations during checkout and order fulfillment. It exposes three related entities, each backed by a different Master Data data entity:

Entity	Data entity	Master Data version	Description
Addresses	AD	v1	Shipping (commercial) and billing (invoice) locations tied to a buyer organization.
Recipients	contact_information	v2	People who can receive orders at one or more B2B addresses.
Locations	customFieldValues	v2	Specific delivery points within an address, such as a dock, department, or internal area.

Because the entities live in different Master Data versions, the available query syntax, pagination conventions, and metadata fields differ per entity. The relevant differences are highlighted in the integration notes for each entity below.

This guide focuses on how these entities relate and on the integration-level details (linking IDs, required setup, query constraints). For the full operation set, parameters, and payload schemas, see the B2B Addresses API reference.

• The store must have B2B Buyer Portal enabled.
• The buyer organization and organizational units must already exist. Their IDs are required when creating addresses and locations.
• For locations, the underlying custom checkout field setting (customFieldId) must already be configured, which is the native behavior for B2B Buyer Portal.

A typical end-to-end integration uses the API in three entities, each independent but linked through IDs:

• Address — Created first, its id becomes the anchor for the other entities.
• Recipient (optional) — References one or more addresses through addressIds. At checkout, recipients linked to the chosen address are offered as order recipients.
• Location (optional) — References a single address through auxId, plus a contract and a custom field setting.

A B2B address represents a shipping or billing destination owned by a buyer organization. Stored in the AD Master Data v1 entity.

Field	Purpose
id	Address UUID returned on creation. Reuse it as addressIds (in recipients) and auxId (in locations). The Id field returned by POST is prefixed (AD-<uuid>), use the unprefixed DocumentId / id value when linking.
userId	ID of the buyer organization that owns the address. This is the id returned by the Create contract request.

Below are constraints that apply to the requests Create B2B address and Update B2B address.

Sending invalid values can break checkout autofill.

• country: Three-letter ISO 3166-1 alpha-3 code (for example, BRA, USA).
• state: Two-letter code (for example, FL, SP); full names are not accepted.
• postalCode: String in the country's exact format (for example, 02999, not 2999); nine-digit formats are not accepted.
• receiverName: Required, but slated to be deprecated in favor of Recipients. Fill it with any value (for example, .).
• geoCoordinates (optional): Array of two doubles ([lat, lon]) or [].

Address search uses Master Data v1 syntax (_where, _fields, _sort). Pagination is controlled by the REST-Range request header (max 100 documents per page); the response includes the total count in REST-Content-Range.

Avoid wildcard (*) and keyword searches at scale — they can temporarily block the endpoint and return 503 Service Unavailable. See Querying documents in Master Data v1 and Pagination in the Master Data API.

• POST Create B2B address
• GET Search B2B addresses
• GET Get B2B address by ID
• PATCH Update B2B address
• DELETE Delete B2B address

A recipient is a person who can be selected as the order recipient at checkout — they may differ from the user placing the order. Stored in the contact_information Master Data v2 entity.

Field	Purpose
addressIds	Array of B2B address IDs the recipient is associated with. At checkout, the chosen shipping address narrows which recipients are offered.
profileId	Optional reference to buyer by UUID.

• Search and get-by-id requests must include _schema=v1 in the query string.
• firstName and lastName are required.
• On partial update, the addressIds array is replaced, not merged. Send the full desired list to add or remove links.
• Deleting a recipient does not affect the addresses referenced through addressIds.
• To find every recipient associated with a given address, query with _where=addressIds={{addressId}}.

• POST Create recipient
• GET Search recipients
• GET Get recipient by ID
• PATCH Update recipient
• DELETE Delete recipient

A location is a specific delivery point within a B2B address (for example, Dock 3456, a department, or an internal area). Locations are values of a custom checkout field, stored in the customFieldValues Master Data v2 entity.

Field	Purpose
contractId	Buyer organization contract the location belongs to.
customFieldId	ID of the location setting (custom field configuration). It must already exist, this API does not create the setting itself. To discover the customFieldId for your account, list the existing settings with GET Search custom field settings and pick the one matching the location feature.
auxId	ID of the B2B address the location belongs to (the id returned by the addresses endpoint).

• value has a maximum length of 22 characters.
• Search requires _schema=v1, _where, and _fields.
• Build the _where filter by combining the linking IDs with AND: Start from contractId and customFieldId (the contract and location setting), then optionally add auxId to narrow down to a specific address.
• To move a location to another address, update its auxId. To rename it, update its value.
• Deleting a location does not affect its address (auxId) or contract (contractId).

• POST Create location
• GET Search locations
• GET Get location
• PATCH Update location
• DELETE Delete location

• B2B Buyer Portal integration overview
• B2B Addresses API reference
• Custom Fields integration