BigCommerce Addresses API

openapi: 3.0.0
info:
  title: BigCommerce Abandoned Cart Emails Addresses API
  version: 3.0.0
  termsOfService: https://www.bigcommerce.com/terms
  description: Abandoned Cart Emails V3 API managing Handlebars-based emails.
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
  variables:
    store_hash:
      default: store_hash
      description: Permanent ID of the BigCommerce store.
  description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Addresses
paths:
  /customers/addresses:
    get:
      description: Returns a list of Customer Addresses. Optional filter parameters can be passed in.
      summary: BigCommerce Get All Customer Addresses
      operationId: getCustomersAddresses
      deprecated: false
      parameters:
      - name: Accept
        in: header
        schema:
          type: string
          default: application/json
      - name: Content-Type
        in: header
        schema:
          type: string
          default: application/json
      - name: page
        in: query
        description: Page number. `page=1`
        schema:
          type: integer
      - in: query
        name: limit
        description: Items count per page. `limit=50`
        schema:
          type: number
      - name: company:in
        in: query
        description: Filter items by company. `company:in=bigcommerce,commongood`
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: name:in
        in: query
        description: Filter items by first_name and last_name. `name:in=James+Moriarty`
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: customer_id:in
        description: Filter by the ID of the customer. Also accepts comma-separated IDs to filter for multiple customers. `customer_id:in=23,24,55`
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: include
        in: query
        description: 'Indicates whether to include customer address sub-resources:

          * `formfields` - address form fields

          `include=formfields`'
        schema:
          type: string
          enum:
          - formfields
      - name: id:in
        in: query
        description: 'Filter items by ID.

          `id:in=4,5,6`'
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      responses:
        '200':
          $ref: '#/components/responses/AddressCollectionResponse'
      tags:
      - Addresses
    post:
      description: "Creates a Customer Address. Multiple customer addresses can be created in one call.\n\n**Required Fields**\n* **customer_id**\n* **first_name**\n* **last_name**\n* **city**\n* **country_code**\n* **address1**\n\n**Notes**\n* A unique customer address is a combination of the following core address fields:\n  * **customer_id**\n  * **first_name**\n  * **last_name**\n  * **company**\n  * **phone**\n  * **address_type**\n  * **address1**\n  * **address2**\n  * **city**\n  * **country_code**\n  * **state_or_province**\n  * **postal_code**\n* 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.\n* The default rate limit for this endpoint is 10 concurrent requests."
      summary: BigCommerce Create a Customer Address
      operationId: createCustomersAddresses
      deprecated: false
      parameters:
      - name: Accept
        in: header
        schema:
          type: string
          default: application/json
      - name: Content-Type
        in: header
        schema:
          type: string
          default: application/json
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/address_Post'
            examples:
              example-1:
                value:
                - 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
        required: true
        x-examples:
          application/json:
          - 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
      responses:
        '200':
          $ref: '#/components/responses/AddressCollectionResponsePostPut'
        '422':
          description: 'The `Address` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Addresses
    put:
      description: "Updates a Customer Address. Multiple customer addresses can be updated in one call.\n\n**Required Fields**\n* **id** -- ID of the *Customer Address*\n\n**Limits**\n* Limit of **3** concurrent requests.\n\n**Notes**\n* A unique customer address is a combination of the following core address fields:\n  * **first_name**\n  * **last_name**\n  * **company**\n  * **phone**\n  * **address_type**\n  * **address1**\n  * **address2**\n  * **city**\n  * **country_code**\n  * **state_or_province**\n  * **postal_code**\n* 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."
      summary: BigCommerce Update a Customer Address
      operationId: updateCustomersAddresses
      deprecated: false
      parameters:
      - name: Accept
        in: header
        schema:
          type: string
          default: application/json
      - name: Content-Type
        in: header
        schema:
          type: string
          default: application/json
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/address_Put'
            examples:
              example-1:
                value:
                - 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:
                value:
                - id: 11
                  form_fields:
                  - name: test
                    value: test
        required: true
        x-examples:
          application/json:
          - first_name: John
            last_name: Doe
            id: 38
            address1: 111 E West Street
            address2: '654'
            city: Akron
            state_or_province: Ohio
            postal_code: '44325'
            country_code: US
            phone: '1234567890'
            address_type: residential
      responses:
        '200':
          $ref: '#/components/responses/AddressCollectionResponsePostPut'
        '422':
          description: 'The `Address` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Addresses
    delete:
      description: 'Deletes a Customer Address.


        **Required Query**

        * id:in -- ID of the *Customer Address*'
      summary: BigCommerce Delete a Customer Address
      operationId: deleteCustomersAddresses
      deprecated: false
      parameters:
      - name: Accept
        in: header
        schema:
          type: string
          default: application/json
      - name: Content-Type
        in: header
        schema:
          type: string
          default: application/json
      - in: query
        name: id:in
        required: true
        description: 'Filter items by ID.

          `id:in=4,5,6`'
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      responses:
        '204':
          description: ''
          headers: {}
      tags:
      - Addresses
components:
  schemas:
    _metaCollection:
      title: _metaCollection
      description: Data about the response, including pagination and collection totals.
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
      x-internal: false
    address_Put:
      title: address_Put
      type: object
      properties:
        first_name:
          description: The first name of the customer address.
          type: string
          minLength: 1
          maxLength: 255
        last_name:
          description: The last name of the customer address.
          type: string
          minLength: 1
          maxLength: 255
        company:
          description: The company of the customer address.
          type: string
          minLength: 0
          maxLength: 255
        address1:
          description: The address 1 line.
          type: string
        address2:
          description: The address 2 line.
          type: string
        city:
          description: The city of the customer address.
          type: string
          minLength: 0
          maxLength: 100
        state_or_province:
          description: The state or province name.
          type: string
          minLength: 0
          maxLength: 100
          example: California
        postal_code:
          description: The postal code of the customer address.
          type: string
          minLength: 0
          maxLength: 30
        country_code:
          description: The country code of the customer address.
          type: string
          minLength: 2
          maxLength: 2
          example: US
        phone:
          description: The phone number of the customer address.
          type: string
          minLength: 0
          maxLength: 50
        address_type:
          title: Address Type
          description: The address type. Residential or Commercial.
          example: residential
          type: string
          enum:
          - residential
          - commercial
        id:
          description: The unique numeric ID of the address.
          type: integer
          format: int32
          example: 1
        form_fields:
          type: array
          description: 'Array of form fields. Controlled by formfields parameter.

            '
          items:
            $ref: '#/components/schemas/formFieldValue'
      required:
      - id
      x-examples:
        example-1:
          value:
          - id: 18
            first_name: sam
      x-internal: false
    formFieldValue:
      title: Generic Form Field Value
      type: object
      required:
      - name
      - value
      properties:
        name:
          type: string
          description: The form field name.
          example: color
        value:
          oneOf:
          - type: string
            example: blue
          - type: number
            format: double
            example: 12.345
          - type: array
            example:
            - red
            - green
            - black
            items:
              type: string
    formFieldValue_Full:
      oneOf:
      - $ref: '#/components/schemas/formFieldValue_Customer'
      - $ref: '#/components/schemas/formFieldValue_Address'
      title: formFieldValue_Full
      x-internal: false
    address_Post:
      title: address_Post
      type: object
      properties:
        first_name:
          type: string
          description: The first name of the customer address.
          minLength: 1
          maxLength: 255
          example: John
        last_name:
          type: string
          description: The last name of the customer address.
          minLength: 1
          maxLength: 255
          example: Doe
        company:
          type: string
          description: The company of the customer address.
          minLength: 0
          maxLength: 255
          example: BigCommerce
        address1:
          type: string
          description: The address 1 line.
          example: 123 Example Street
        address2:
          type: string
          description: The address 2 line.
          example: Building 4
        city:
          type: string
          description: The city of the customer address.
          minLength: 0
          maxLength: 100
          example: Austin
        state_or_province:
          type: string
          description: 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.
          example: Texas
          minLength: 0
          maxLength: 100
        postal_code:
          type: string
          description: The postal code of the customer address. It is required for countries that need postal codes to complete an address.
          minLength: 0
          maxLength: 30
          example: '78759'
        country_code:
          type: string
          description: The country code of the customer address.
          example: US
          minLength: 2
          maxLength: 2
        phone:
          type: string
          description: The phone number of the customer address.
          minLength: 0
          maxLength: 50
          example: '15551234567'
        address_type:
          title: Address Type
          description: The address type. Residential or Commercial.
          example: residential
          type: string
          enum:
          - residential
          - commercial
        customer_id:
          description: The customer ID.
          type: integer
          format: int32
          example: 1
        form_fields:
          type: array
          description: 'The address custom form field values

            '
          items:
            $ref: '#/components/schemas/formFieldValue'
      required:
      - first_name
      - last_name
      - address1
      - city
      - country_code
      - customer_id
      x-examples:
        Example:
          value:
            first_name: John
            last_name: Doe
            company: BigCommerce
            address1: 123 Example Street
            address2: Building 4
            city: Austin
            state_or_province: Texas
            postal_code: '78759'
            country_code: US
            phone: '15551234567'
            address_type: residential
            customer_id: 1
      x-internal: false
    Pagination:
      title: Pagination
      description: Data about the response, including pagination and collection totals.
      type: object
      properties:
        total:
          description: Total number of items in the result set.
          type: integer
          format: int32
        count:
          description: Total number of items in the collection response.
          type: integer
          format: int32
        per_page:
          description: The amount of items returned in the collection per page, controlled by the limit parameter.
          type: integer
          format: int32
        current_page:
          description: The page you are currently on within the collection.
          type: integer
          format: int32
        total_pages:
          description: The total number of pages in the collection.
          type: integer
          format: int32
        links:
          $ref: '#/components/schemas/Links'
      x-internal: false
    MetaOpen:
      title: Response meta
      type: object
      properties: {}
      additionalProperties: true
      description: Response metadata.
    ErrorResponse:
      title: Error Response
      type: object
      properties:
        status:
          description: The HTTP status code.
          type: integer
          format: int32
        title:
          description: The error title describing the particular error.
          type: string
        type:
          description: A link to a list of BigCommerce API status codes.
          type: string
        instance:
          type: string
        errors:
          type: object
          additionalProperties:
            type: string
      x-internal: false
    Links:
      title: Links
      description: Pagination links for the previous and next parts of the whole collection.
      type: object
      properties:
        previous:
          description: Link to the previous page returned in the response.
          type: string
        current:
          description: Link to the current page returned in the response.
          type: string
        next:
          description: Link to the next page returned in the response.
          type: string
    formFieldValue_Customer:
      title: Customer Form Field Value
      type: object
      required:
      - customer_id
      - name
      - value
      properties:
        name:
          type: string
          description: The form field name.
          example: color
        value:
          oneOf:
          - type: string
            example: blue
          - type: number
            format: double
            example: 12.345
          - type: array
            example:
            - red
            - green
            - black
            items:
              type: string
        customer_id:
          type: integer
    formFieldValue_Address:
      title: Customer Address Form Field Value
      type: object
      required:
      - address_id
      - name
      - value
      properties:
        name:
          type: string
          description: The form field name.
          example: color
        value:
          oneOf:
          - type: string
            example: blue
          - type: number
            format: double
            example: 12.345
          - type: array
            example:
            - red
            - green
            - black
            items:
              type: string
        address_id:
          type: integer
          description: The Customer Address ID.
          example: 1
      x-internal: false
  responses:
    AddressCollectionResponsePostPut:
      description: ''
      content:
        application/json:
          schema:
            anyOf:
            - title: AddressCollectionResponse
              description: Response payload for the BigCommerce API.
              example:
                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: {}
              properties:
                data:
                  type: array
                  items:
                    title: Address
                    type: object
                    properties:
                      address1:
                        description: The address 1 line.
                        type: string
                      address2:
                        description: The address 2 line.
                        type: string
                      address_type:
                        title: Address Type
                        description: The address type. Residential or Commercial.
                        example: residential
                        type: string
                        enum:
                        - residential
                        - commercial
                      city:
                        description: The city of the customer address.
                        type: string
                        minLength: 0
                        maxLength: 100
                      company:
                        description: The company of the customer address.
                        type: string
                        minLength: 0
                        maxLength: 255
                      country:
                        description: The country name of the customer address.
                        type: string
                      country_code:
                        description: The country code of the customer address.
                        type: string
                        minLength: 2
                        maxLength: 2
                      customer_id:
                        description: The customer ID.
                        type: integer
                        format: int32
                      first_name:
                        description: The first name of the customer address.
                        type: string
                        minLength: 1
                        maxLength: 255
                      id:
                        description: The unique numeric ID of the address.
                        type: integer
                        format: int32
                      last_name:
                        description: The last name of the customer address.
                        type: string
                        minLength: 1
                        maxLength: 255
                      phone:
                        description: The phone number of the customer address.
                        type: string
                        minLength: 0
                        maxLength: 50
                      postal_code:
                        description: The postal code of the customer address.
                        type: string
                        minLength: 0
                        maxLength: 30
                      state_or_province:
                        description: The state or province name
                        type: string
                        minLength: 0
                        maxLength: 100
                      form_fields:
                        description: Array of form fields. Controlled by `formfields` parameter.
                        type: array
                        items:
                          $ref: '#/components/schemas/formFieldValue_Full'
                meta:
                  $ref: '#/components/schemas/MetaOpen'
            - title: DuplicateAddressCollectionResponse
              example: {}
            type: object
            properties:
              data:
                type: array
                items:
                  title: Address
                  type: object
                  properties:
                    address1:
                      description: The address 1 line.
                      type: string
                    address2:
                      description: The address 2 line.
                      type: string
                    address_type:
                      title: Address Type
                      description: The address type. Residential or Commercial
                      example: residential
                      type: string
                      enum:
                      - residential
                      - commercial
                    city:
                      description: The city of the customer address.
                      type: string
                      minLength: 0
                      maxLength: 100
                    company:
                      description: The company of the customer address.
                      type: string
                      minLength: 0
                      maxLength: 255
                    country:
                      description: The country name of the customer address.
                      type: string
                    country_code:
                      description: The country code of the customer address.
                      type: string
                      minLength: 2
                      maxLength: 2
                    customer_id:
                      description: The customer ID.
                      type: integer
                      format: int32
                    first_name:
                      description: The first name of the customer address.
                      type: string
                      minLength: 1
                      maxLength: 255
                    id:
                      description: The unique numeric ID of the address.
                      type: integer
                      format: int32
                    last_name:
                      description: The last name of the customer address.
                      type: string
                      minLength: 1
                      maxLength: 255
                    phone:
                      description: The phone number of the customer address.
                      type: string
                      minLength: 0
                      maxLength: 50
                    postal_code:
                      description: The postal code of the customer address.
                      type: string
                      minLength: 0
                      maxLength: 30
                    state_or_province:
                      description: The state or province name.
                      type: string
                      minLength: 0
                      maxLength: 100
                    form_fields:
                      description: Array of form fields. Controlled by `formfields` parameter.
                      type: array
                      items:
                        allOf:
                        - $ref: '#/components/schemas/formFieldValue_Address'
                        title: Customer Address Form Field Value
              meta:
                $ref: '#/components/schemas/MetaOpen'
          examples:
            application/json:
              value:
                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:
              value: {}
    AddressCollectionResponse:
      description: ''
      content:
        application/json:
          schema:
            title: AddressCollectionResponse
            description: Response payload for the BigCommerce API.
            type: object
            properties:
              data:
                type: array
                items:
                  title: Address
                  type: object
                  properties:
                    address1:
                      description: The address 1 line.
                      type: string
                    address2:
                      description: The address 2 line.
                      type: string
                    address_type:
                      title: Address Type
                      description: The address type. Residential or Commercial.
                      example: residential
                      type: string
                      enum:
                      - residential
                      - commercial
                    city:
                      description: The city of the customer address.
                      type: string
                      minLength: 0
                      maxLength: 100
                    company:
                      description: The company of the customer address.
                      type: string
                      minLength: 0
                      maxLength: 255
                    country:
                      description: The country name of the customer address.
                      type: string
                    country_code:
                      description: The country code of the customer address.
                      type: string
                      minLength: 2
                      maxLength: 2
                    customer_id:
                      description: The customer ID.
                      type: integer
                      format: int32
                    first_name:
                      description: The first name of the customer address.
                      type: string
                      minLength: 1
                      maxLength: 255
                    id:
                      description: The unique numeric ID of the address.
                      type: integer
                      format: int32
                    last_name:
                      description: The last name of the customer address.
                      type: string
                      minLength: 1
                      maxLength: 255
                    phone:
                      description: The phone number of the customer address.
                      type: string
                      minLength: 0
                      maxLength: 50
                    postal_code:
                      description: The postal code of the customer address.
                      type: string
                      minLength: 0
                      maxLength: 30
                    state_or_province:
                      description: The state or province name
                      type: string
                      minLength: 0
                      maxLength: 100
                    form_fields:
                      description: Array of form fields. Controlled by `formfields` parameter.
                      type: array
                      items:
                        allOf:
                        - $ref: '#/components/schemas/formFieldValue_Address'
                        title: Customer Address Form Field Value
                  required:
                  - address1
                  - city
                  - country_code
                  - customer_id
                  - first_name
                  - id
                  - last_name
                  - postal_code
                  - state_or_province
              meta:
                $ref: '#/components/schemas/_metaCollection'
          examples:
            response:
              value:
                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
  securitySchemes:
    X-Auth-Token:
      name: X-Auth-Token
      description: '#

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/bigcommerce-addresses-api-openapi.yml