Skip to Content
B2b EditionB2B Edition APIsServer to Server Management APIsAddressAddressesAddresses

Addresses

Get a Country

GET /countries

Request

Retrieves country information based on the country name or two-letter code entered in the parameters. The response can be used to provide a valid country name or code in Company addresses.

Use the searchType parameter to specify whether you are searching by a country's name or its two-letter ISO code, and then add the appropriate value for the country to the q parameter. This endpoint only accepts country name values in English, but you can set the searchBy paramteter to 1 to retrieve country information with the standard ISO code instead.

Authentication

  • X-Auth-Token in header

Parameters

  • X-Store-Hash in header - string
    required
    The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
    Example: abc123
  • searchType in query0 - integer
    required
    Determines whether you are searching by a country's name (0) or its two-letter ISO code (1).

    Allowed: 0 | 1

  • q in query - string
    required
    The country's name or its two-letter ISO code, depending on the specified searchType.
    Example: US (the searchType should be 1); United States (the searchType should be 0)

example

Response

OK

Body

object | application/json

  • code    number
    required

    Default: 200

  • data    object
    required

  • meta    object
    required

example

Get a State

GET /states

Request

Retrieves state or province information based on the state name or two-letter code entered in the parameters. The response can be used to provide a valid state name or code in Company addresses.

Use the country parameter to specify the country associated with the queried state. If left blank, the endpoint uses the United States by default.

Note that only the countries listed below will return state or province values. When creating or updating addresses in these countries, you must include state information.

  • Argentina
  • Australia
  • Austria
  • Brazil
  • Canada
  • Chile
  • Germany
  • India
  • Indonesia
  • Ireland
  • Italy
  • Japan
  • Malaysia
  • Mexico
  • Myanmar
  • New Zealand
  • Philippines
  • Qatar
  • Romania
  • South Africa
  • Spain
  • Switzerland
  • United Arab Emirates
  • United States (default)

Use the searchType parameter to specify whether you are searching by a state's name or its two-letter ISO code, and then add the appropriate value for the state to the q parameter.

Authentication

  • X-Auth-Token in header

Parameters

  • X-Store-Hash in header - string
    required
    The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
    Example: abc123
  • searchType in query0 - integer
    required
    Determines whether you are searching by a state or province's name (0) or its two-letter ISO code (1). This parameter also defines the value type for the country parameter.

    Allowed: 0 | 1

  • q in query - string
    required

    The state's name or its two-letter ISO code, depending on the specified searchType.

    Note: The state information entered for the parameter must correspond to the country specified in the country value.

    Example: TX (the searchType should be 1); Texas (the searchType should be 0)
  • country in query with default of US / United States - string
    The country's name or its two-letter ISO code, depending on the specified searchType.
    Example: US(the searchType should be 1), United States(the searchType should be 0)

example

Response

OK

Body

object | application/json

  • code    number
    required

    Default: 200

  • data    object
    required

  • meta    object
    required

example

Get All Addresses

GET /addresses

Request

Retrieves a list of addresses across all Company accounts. Use the parameters to filter results by different attributes like creation date, Company account, and country.

By default, the response does not include address extra fields and values. To include this information, use the isIncludeExtraFields parameter and provide a value of 1.

Authentication

  • X-Auth-Token in header

Parameters

  • X-Store-Hash in header - string
    required
    The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
    Example: abc123
  • limit in query with default of 10 - integer
    Determines the number of records to return per page. If left blank, this defaults to 10.
    Example: 15
  • offset in query0 - integer
    The number of results to skip before returning the first result. If left blank, this defaults to 0.
    Example: 5
  • minModified in query - integer
    Enter a Unix timestamp to retrieve all addresses updated after that time.
    Example: 1622619778
  • maxModified in query - integer
    Enter a Unix timestamp to retrieve all addresses updated before that time.
    Example: 1622619778
  • minCreated in query - integer
    Enter a Unix timestamp to retrieve all addresses created after that time.
    Example: 1622619778
  • maxCreated in query - integer
    Enter a Unix timestamp to retrieve all addresses created before that time.
    Example: 1622619778
  • companyId in query - integer
    Enter the unique numeric ID of the Company account to return its addresses.
    Example: 123456
  • isBilling in query - boolean
    Indicate whether you want to filter for or against billing addresses in the response.
    Example: true
  • isShipping in query - boolean
    Indicate whether you want to filter for or against shipping addresses in the response.
    Example: true
  • isIncludeExtraFields in query0 - integer
    Indicate whether you want to include (1) or exclude (0) address extra fields in the response.

    Allowed: 0 | 1

  • firstName in query - string
    Filter for addresses with a specific first name.
  • lastName in query - string
    Filter for addresses with a specific last name.
  • address in query - string
    Enter the first or second address line to return relevant addresses.
  • city in query - string
    Filter for addresses from a specific city.
  • country in query - string
    Filter for addresses from a specific country. Use the country's full name or its two-letter ISO code.
  • state in query - string
    Filter for addresses from a specific state or province. Use the state's full name or its two-letter ISO code.
  • zipCode in query - string
    Filter for addresses from a specific postal code.
  • phoneNumber in query - string
    Filter for addresses with a specific phone number.
  • externalId[] in query - string
    Filter by an external ID assigned to addresses in a third-party system, such as an ERP.

example

Response

OK

Body

object | application/json

  • code    integer
    required

    HTTP Response Code

    Default: 200

  • data    object
    required

  • meta    object
    required

example

Create a Company Address

POST /addresses

Request

Creates an address for a Company account. Use Bulk Create Addresses to create multiple addresses in a single request.

Considerations

In addition to the minimum-required fields presented in the request body example, you may need to supply a stateName or a stateCode if the address is in a designated country.

If you have set one or more address extra fields as mandatory, you must include the extraFields object in the request body. If an extra field is configured to accept only unique values, each fieldValue must be distinct for a successful request.

You can create Company addresses without assigning them as billing or shipping addresses. However, Company users cannot use addresses at checkout without a billing or shipping designation.

Authentication

  • X-Auth-Token in header

Parameters

  • X-Store-Hash in header - string
    required
    The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
    Example: abc123

Body

object | application/json

  • firstName    string
    required

    The first name on the address.
    Example: Marie

  • lastName    string
    required

    The last name on the address.
    Example: Curie

  • phoneNumber    string

    The phone number on the address.
    Example: 512-200-1234

  • zipCode    string

    The postal code on the address.
    Example: 78704

  • addressLine1    string
    required

    The first line of the address.
    Example: 512 Bluebonnet Lane

  • addressLine2    string

    The second line of the address.
    Example: Building 1

  • city    string
    required

    The city on the address.
    Example: Austin

  • stateName    string
    required

    The full name of the state or province on the address. This must correspond to stateCode in the request if the state or province is required for the country.
    Example: Texas

  • countryName    string
    required

    The full name of the country on the address. Use Get a Country to retrieve valid country names.
    Example: United States

  • stateCode    string

    The two-letter ISO code for the state or province on the address. Omit this field when adding state or province information for an unsupported country.
    Example: TX

  • countryCode    string

    The two-letter ISO code for the country on the address. Use Get a Country to retrieve valid country codes.
    Example: US

  • companyId    integer
    required

    The unique numeric ID of the Company account.
    Example: 123456

  • isBilling    boolean

    Indicates whether the address is a billing address.
    Example: true

  • isShipping    boolean

    Indicates whether the address is a shipping address.
    Example: true

  • isDefaultBilling    boolean

    Indicates whether the address is the default billing address.
    Example: true

  • isDefaultShipping    boolean

    Indicates whether the address is the default shipping address.
    Example: true

  • label    string

    The label used on the storefront to identify the address.
    Example: Austin Warehouse

  • externalId    string

    An external ID assigned to the address in a third-party system, such as an ERP.
    Example: 123456

  • extraFields    array[object]

    Enter extra field information for the address.

Minimum-required fields

All fields

Response

OK

Body

object | application/json

  • code    integer
    required

    Default: 200

  • data    object
    required

  • meta    object
    required

example

Get an Address

GET /addresses/{addressId}

Request

Retrieves detailed information on a single Company address.

Authentication

  • X-Auth-Token in header

Parameters

  • X-Store-Hash in header - string
    required
    The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
    Example: abc123
  • addressId in path - string
    required
    The unique numeric identifier of the Company address.

example

Response

OK

Body

object | application/json

  • code    integer
    required

    Default: 200

  • data    object
    required

  • meta    object
    required

example

Update an Address

PUT /addresses/{addressId}

Request

Edits details of an existing Company address.

There are no required fields for this endpoint, but you must include isBilling or isShipping to change the value of isDefaultBilling or isDefaultShipping respectively.

When changing the countryName, you must also update the countryCode. Updating the countryCode by itself will automatically adjust the countryName. If you are changing the countryCode to a country that supports states, you must also include the stateCode with a valid two-letter code value for the state.

Authentication

  • X-Auth-Token in header

Parameters

  • X-Store-Hash in header - string
    required
    The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
    Example: abc123
  • addressId in path - string
    required
    The unique numeric identifier of the Company address.

Body

application/json

  • firstName    string

    The first name on the address.
    Example: Marie

  • lastName    string

    The last name on the address.
    Example: Curie

  • phoneNumber    string

    The phone number on the address.
    Example: 512-200-1234

  • zipCode    string

    The postal code on the address.
    Example: 78704

  • addressLine1    string

    The first line of the address.
    Example: 512 Bluebonnet Lane

  • addressLine2    string

    The second line of the address.
    Example: Building 1

  • city    string

    The city on the address.
    Example: Austin

  • stateName    string

    The full name of the state or province on the address. This must correspond to stateCode in the request if the state or province is required for the country.
    Example: Texas

  • countryName    string

    The full name of the country on the address. Use Get a Country to retrieve valid country names.
    Example: United States

  • stateCode    string

    The two-letter ISO code for the state or province on the address. Omit this field when adding state or province information for an unsupported country.
    Example: TX

  • countryCode    string

    The two-letter ISO code for the country on the address. Use Get a Country to retrieve valid country codes.
    Example: US

  • companyId    integer

    The unique numeric ID of the Company account.
    Example: 123456

  • isBilling    boolean

    Indicates whether the address is a billing address.
    Example: true

  • isShipping    boolean

    Indicates whether the address is a shipping address.
    Example: true

  • isDefaultBilling    boolean

    Indicates whether the address is the default billing address.
    Example: true

  • isDefaultShipping    boolean

    Indicates whether the address is the default shipping address.
    Example: true

  • label    string

    The label used on the storefront to identify the address.
    Example: Austin Warehouse

  • externalId    string

    An external ID assigned to the address in a third-party system, such as an ERP.
    Example: 123456

  • extraFields    array[object]

    Enter extra field information for the address.

example

Response

OK

Body

object | application/json

  • code    integer
    required

    Default: 200

  • data    object
    required

  • meta    object
    required

example

Delete an Address

DELETE /addresses/{addressId}

Request

Permanently removes an address from a Company account. Deleting addresses does not remove them from existing quotes, invoices, and orders, but the address is no longer available for future records.

Authentication

  • X-Auth-Token in header

Parameters

  • X-Store-Hash in header - string
    required
    The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
    Example: abc123
  • addressId in path - string
    required
    The unique numeric identifier of the Company address.

example

Response

OK

Body

object | application/json

  • code    integer
    required

    Default: 200

  • data    object
    required

  • meta    object
    required

example

Bulk Create Addresses

POST /addresses/bulk

Request

Creates multiple addresses for up to 10 addresses at a time. You can create addresses for different Company accounts in a single request by entering a different companyid value for each address object.

See Create a Company Address for considerations related to creating one or more addresses.

Authentication

  • X-Auth-Token in header

Parameters

  • X-Store-Hash in header - string
    required
    The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
    Example: abc123

Body

object | application/json

  • firstName    string
    required

    The first name on the address.
    Example: Marie

  • lastName    string
    required

    The last name on the address.
    Example: Curie

  • phoneNumber    string

    The phone number on the address.
    Example: 512-200-1234

  • zipCode    string

    The postal code on the address.
    Example: 78704

  • addressLine1    string
    required

    The first line of the address.
    Example: 512 Bluebonnet Lane

  • addressLine2    string

    The second line of the address.
    Example: Building 1

  • city    string
    required

    The city on the address.
    Example: Austin

  • stateName    string
    required

    The full name of the state or province on the address. This must correspond to stateCode in the request if the state or province is required for the country.
    Example: Texas

  • countryName    string
    required

    The full name of the country on the address. Use Get a Country to retrieve valid country names.
    Example: United States

  • stateCode    string

    The two-letter ISO code for the state or province on the address. Omit this field when adding state or province information for an unsupported country.
    Example: TX

  • countryCode    string

    The two-letter ISO code for the country on the address. Use Get a Country to retrieve valid country codes.
    Example: US

  • companyId    integer
    required

    The unique numeric ID of the Company account.
    Example: 123456

  • isBilling    boolean

    Indicates whether the address is a billing address.
    Example: true

  • isShipping    boolean

    Indicates whether the address is a shipping address.
    Example: true

  • isDefaultBilling    boolean

    Indicates whether the address is the default billing address.
    Example: true

  • isDefaultShipping    boolean

    Indicates whether the address is the default shipping address.
    Example: true

  • label    string

    The label used on the storefront to identify the address.
    Example: Austin Warehouse

  • externalId    string

    An external ID assigned to the address in a third-party system, such as an ERP.
    Example: 123456

  • extraFields    array[object]

    Enter extra field information for the address.

Two addresses

Response

OK

Body

object | application/json

  • code    integer
    required

    HTTP Response Code

    Default: 200

  • data    object
    required

  • meta    object
    required

Two addresses

Get Address Extra Field Configs

GET /addresses/extra-fields

Request

Returns a list of available extra fields configurations for Company addresses.

We recommend caching the response results to avoid frequent API requests.

Authentication

  • X-Auth-Token in header

Parameters

  • X-Store-Hash in header - string
    required
    The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
    Example: abc123
  • offset in query0 - integer
    The number of results to skip before returning the first result. If left blank, this defaults to 0.
    Example: 5
  • limit in query with default of 10 - integer
    Determines the number of records to return per page. If left blank, this defaults to 10.
    Example: 15

example

Response

OK

Body

object | application/json

  • code    integer
    required

    Default: 200

  • data    array[object]
    required

  • meta    object
    required

example

Did you find what you were looking for?
AddressAuthentication