Docs
Management API
Customers V3
Addresses

Addresses

Get All Customer Addresses

GET /customers/addresses

Request

Returns a list of Customer Addresses. Optional filter parameters can be passed in.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
  • Content-Type in header with default of application/json - string
  • page in query - integer
    Page number. page=1
  • limit in query - number
    Items count per page. limit=50
  • company:in in query - array
    Filter items by company. company:in=bigcommerce,commongood
    Type: array[string]
  • name:in in query - array
    Filter items by first_name and last_name. name:in=James+Moriarty
    Type: array[string]
  • customer_id:in in query - array
    Filter by the ID of the customer. Also accepts comma-separated IDs to filter for multiple customers. customer_id:in=23,24,55
    Type: array[integer]
  • include in query - array

    Indicates whether to include customer address sub-resources:

    • formfields
      • address form fields include=formfields
    Type: array[string]

    Allowed: formfields

  • id:in in query - array

    Filter items by ID. id:in=4,5,6

    Type: array[integer]

example

curl --request GET \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/customers/addresses' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

Body

object | application/json
Response payload for the BigCommerce API.

  • data    array[object]

  • meta    object

    Data about the response, including pagination and collection totals.

response

{
"data": [
{
"address1": "123 Example Street",
"address2": "Building 4",
"address_type": "residential",
"city": "Austin",
"company": "BigCommerce",
"country": "United States",
"country_code": "US",
"customer_id": 1,
"first_name": "John",
"id": 18,
"last_name": "Doe",
"phone": "15551234567",
"postal_code": "78759",
"state_or_province": "Texas"
}
],
"meta": {
"pagination": {
"total": 1,
"count": 1,
"per_page": 50,
"current_page": 1,
"total_pages": 1
}
}
}

Create a Customer Address

POST /customers/addresses

Request

Creates a Customer Address. Multiple customer addresses can be created in one call.

Required Fields

  • customer_id
  • first_name
  • last_name
  • city
  • country_code
  • address1
  • state_or_province
  • postal_code

Notes

  • A unique customer address is a combination of the following core address fields:
    • customer_id
    • first_name
    • last_name
    • company
    • phone
    • address_type
    • address1
    • address2
    • city
    • country_code
    • state_or_province
    • postal_code
  • An attempt to create an address that already exists will result in no change to the address or custom form field values, an HTTP 200 return code, and the address will be absent from the response body.
  • The default rate limit for this endpoint is 10 concurrent requests.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
  • Content-Type in header with default of application/json - string

Body

array | application/json

  • first_name    string
    required

    The first name of the customer address.
    >= 1 characters<= 255 characters
    Example: John

  • last_name    string
    required

    The last name of the customer address.
    >= 1 characters<= 255 characters
    Example: Doe

  • company    string

    The company of the customer address.
    >= 0 characters<= 255 characters
    Example: BigCommerce

  • address1    string
    required

    The address 1 line.
    Example: 123 Example Street

  • address2    string

    The address 2 line.
    Example: Building 4

  • city    string
    required

    The city of the customer address.
    >= 0 characters<= 100 characters
    Example: Austin

  • state_or_province    string
    required

    The state or province name spelled out in full. It is required for countries that need a state/province to complete an address. State or province codes not accepted.
    >= 0 characters<= 100 characters
    Example: Texas

  • postal_code    string
    required

    The postal code of the customer address. It is required for countries that need postal codes to complete an address.
    >= 0 characters<= 30 characters
    Example: 78759

  • country_code    string
    required

    The country code of the customer address.
    >= 2 characters<= 2 characters
    Example: US

  • phone    string

    The phone number of the customer address.
    >= 0 characters<= 50 characters
    Example: 15551234567

  • address_type    string

    The address type. Residential or Commercial.

    Allowed: residential | commercial

    Example: residential

  • customer_id    integer
    required

    The customer ID.
    Example: 1

  • form_fields    array[object]

    The address custom form field values

example-1

[
{
"first_name": "John",
"last_name": "Doe",
"address1": "111 E West Street",
"address2": "654",
"city": "Akron",
"state_or_province": "Ohio",
"postal_code": "44325",
"country_code": "US",
"phone": "1234567890",
"address_type": "residential",
"customer_id": 11,
"form_fields": [
{
"name": "test",
"value": "test"
}
]
}
]

Response

Body

object | application/json
Any of:

  • data    array[object]

  • meta    object

    Response metadata.

  • data    array[object]

  • meta    object

    Response metadata.

application/json

{
"address1": "123 Example Street",
"address2": "Building 4",
"address_type": "residential",
"city": "Austin",
"company": "BigCommerce",
"country": "United States",
"country_code": "US",
"customer_id": 1,
"first_name": "John",
"id": 18,
"last_name": "Doe",
"phone": "15551234567",
"postal_code": "78759",
"state_or_province": "Texas",
"meta": {}
}

duplicate

{}

Update a Customer Address

PUT /customers/addresses

Request

Updates a Customer Address. Multiple customer addresses can be updated in one call.

Required Fields

  • id -- ID of the Customer Address

Limits

  • Limit of 3 concurrent requests.

Notes

  • A unique customer address is a combination of the following core address fields:
    • first_name
    • last_name
    • company
    • phone
    • address_type
    • address1
    • address2
    • city
    • country_code
    • state_or_province
    • postal_code
  • An attempt to update an address such that it becomes identical to another address that already exists will result in no change to the target address or custom form field values. The response will have an HTTP 200 return code, and the address will be absent from the response body.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
  • Content-Type in header with default of application/json - string

Body

array | application/json

  • first_name    string

    The first name of the customer address.
    >= 1 characters<= 255 characters

  • last_name    string

    The last name of the customer address.
    >= 1 characters<= 255 characters

  • company    string

    The company of the customer address.
    >= 0 characters<= 255 characters

  • address1    string

    The address 1 line.

  • address2    string

    The address 2 line.

  • city    string

    The city of the customer address.
    >= 0 characters<= 100 characters

  • state_or_province    string

    The state or province name.
    >= 0 characters<= 100 characters
    Example: California

  • postal_code    string

    The postal code of the customer address.
    >= 0 characters<= 30 characters

  • country_code    string

    The country code of the customer address.
    >= 2 characters<= 2 characters
    Example: US

  • phone    string

    The phone number of the customer address.
    >= 0 characters<= 50 characters

  • address_type    string

    The address type. Residential or Commercial.

    Allowed: residential | commercial

    Example: residential

  • id    integer
    required

    The unique numeric ID of the address.
    Example: 1

  • form_fields    array[object]

    Array of form fields. Controlled by formfields parameter.

example-1

[
{
"id": 11,
"first_name": "John",
"last_name": "Doe",
"address1": "111 E West Street",
"address2": "654",
"city": "Akron",
"state_or_province": "Ohio",
"postal_code": "44325",
"country_code": "US",
"phone": "1234567890",
"address_type": "residential",
"form_fields": [
{
"name": "test",
"value": "test"
}
]
}
]

example-2-form-fields

[
{
"id": 11,
"form_fields": [
{
"name": "test",
"value": "test"
}
]
}
]

Response

Body

object | application/json
Any of:

  • data    array[object]

  • meta    object

    Response metadata.

  • data    array[object]

  • meta    object

    Response metadata.

application/json

{
"address1": "123 Example Street",
"address2": "Building 4",
"address_type": "residential",
"city": "Austin",
"company": "BigCommerce",
"country": "United States",
"country_code": "US",
"customer_id": 1,
"first_name": "John",
"id": 18,
"last_name": "Doe",
"phone": "15551234567",
"postal_code": "78759",
"state_or_province": "Texas",
"meta": {}
}

duplicate

{}

Delete a Customer Address

DELETE /customers/addresses

Request

Deletes a Customer Address.

Required Query

  • id:in -- ID of the Customer Address

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
  • Content-Type in header with default of application/json - string
  • id:in in query - array
    required

    Filter items by ID. id:in=4,5,6

    Type: array[integer]

example

curl --request DELETE \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/customers/addresses' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

Did you find what you were looking for?
Delete CustomersGet All Customer Addresses