B2B Addresses API

The B2B Addresses API allows you to manage B2B addresses and their related entities in VTEX. A B2B address stores location data used for shipping and billing. Addresses, recipients, and locations are stored in Master Data data entities.

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

B2B address requirements

B2B addresses must follow these rules:

Field	Required	Description
addressType	Yes	Type of address. Use commercial for shipping (delivery) or invoice for billing (payment).
receiverName	Yes	Name of the person receiving orders at this address. This field will be deprecated in favor of the Recipients feature, but it must be filled with some value (for example, .).
country	Yes	Three-letter ISO 3166-1 alpha-3 country code (for example, BRA or USA).
state	Yes	Two-letter state or province code (for example, FL or SP). Full names such as Florida are not accepted.
postalCode	Yes	String following the exact country format (for example, 02999 instead of 2999). Nine-digit formats are not accepted.
geoCoordinates	No	Array of doubles representing latitude and longitude (for example, [28.48, -81.20]), or an empty array [].

Addresses

Stored in the AD data entity. A B2B address represents a shipping or billing location tied to a buyer organization.

Recipients

Stored in the contact_information data entity. A recipient represents a person who can receive orders at one or more B2B addresses. Recipients are linked to B2B addresses through the addressIds field.

Locations

A location is a specific delivery point within a site, such as a dock, department, or internal area. For example, freight may be consigned to the company's street address while the actual delivery is to Dock 3456. The Locations API is based in the Custom Fields API.

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.