BigCommerce
BigCommerce Customers API

The Customers API from BigCommerce — 1 operation(s) for customers.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  title: BigCommerce Abandoned Cart Emails Customers 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: Customers
paths:
  /customers:
    get:
      description: 'Returns a list of Customers. Optional filter parameters can be passed in.


        **Notes**


        Attribute names are not available on the customer object.'
      summary: BigCommerce Get All Customers
      tags:
      - Customers
      operationId: getCustomers
      deprecated: false
      parameters:
      - 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: id:in
        in: query
        description: 'Filter items by ID.

          `id:in=4,5,6`'
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - 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: customer_group_id:in
        in: query
        description: Filter items by customer_group_id. `customer_group_id:in=5,6`
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: date_created
        in: query
        description: Filter items by date_created. `date_created=2018-09-05T13:43:54`
        schema:
          type: string
          format: date-time
      - name: date_created:max
        in: query
        description: Filter items by maximum date_created. `date_created:max=2018-09-10`
        schema:
          type: string
      - name: date_created:min
        in: query
        description: Filter items by date_created. `date_created:min=2018-09-05`
        schema:
          type: string
          format: date-time
      - name: date_modified
        in: query
        description: Filter items by date_modified. `date_modified=2018-09-05T13:45:03`
        schema:
          type: string
          format: date-time
      - name: date_modified:min
        in: query
        description: Filter items by minimum date_modified. `date_modified:min=2019-09-04T:00:00:00` or `date_modified:min=2019-09-04`
        schema:
          type: string
      - name: date_modified:max
        in: query
        description: Filter items by maximum date_modified. `date_modified:max=2018-09-05T13:45:03` or `date_modified:max=2019-09-04`
        schema:
          type: string
          format: date-time
      - name: email:in
        in: query
        description: Filter items by email. `email:in=janedoe@example.com`
        schema:
          type: string
      - name: name:in
        in: query
        description: Filter items by first_name and last_name. `name=james moriarty`
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: name:like
        in: query
        description: 'Filter items by substring in first_name and last_name.

          `name:like=moriarty, sherlock`

          Concatenates the first_name and last_name fields.'
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: registration_ip_address:in
        in: query
        description: 'Filter items by registration_ip_address. If the customer was created using the API, then registration address is blank.

          `registration_ip_address:in=12.345.6.789`'
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      - name: include
        in: query
        description: "Indicates whether to include customer sub-resources:\n * `addresses` - customer addresses\n * `storecredit` - store credit\n * `attributes` - customer attributes and address attributes\n * `formfields` - customer and address form fields\n * `shopper_profile_id` - the ID of the shopper profile associated with the customer (Beta)\n * `segment_ids`- segments the customer belongs to (Beta)\n\n `include=addresses,storecredit,attributes,formfields,shopper_profile_id,segment_ids`"
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - addresses
            - storecredit
            - attributes
            - formfields
            - shopper_profile_id
            - segment_ids
      - in: query
        name: sort
        description: 'Sort items by date_created, date_modified, or last_name:* `date_created:asc` - date created, ascending* `date_created:desc` - date created, descending* `last_name:asc` - last name, ascending* `last_name:desc` - last name, descending * `date_modified:asc` - date modified, ascending* `date_modified:desc`- date modified, descending  Example: `sort=last_name:asc`'
        schema:
          type: string
          enum:
          - date_created:asc
          - date_created:desc
          - last_name:asc
          - last_name:desc
          - date_modified:asc
          - date_modified:desc
      responses:
        '200':
          $ref: '#/components/responses/CustomerCollectionResponse'
    post:
      description: "Creates Customers. Create up to 10 customers in one call.\n\n**Required Fields**\n* last_name\n* first_name\n* email\n\n**Required Fields Customer Address**\n* first_name\n* city\n* country_code\n* last_name\n* address1\n\n**Required Fields Attributes**\n* Attributes must be [created](/docs/rest-management/customers/customer-attributes#create-a-customer-attribute) **BEFORE** creating a customer.\n* attribute_id\n* attribute_value -- This is input as a string, regardless of the [Type](/docs/rest-management/customers/customer-attributes#create-a-customer-attribute).\n\n**Notes**\n\nA customer can be created with global access or channel-specific access.\n* **Global access:**\n  * Make sure the channel has `allow_global_logins` enabled. This is on by default only for the default storefront. Find more info at [Customer Settings > Channel](/docs/rest-management/customers/customer-settings-channel).\n  * Omit `channel_ids` field, or provide `channel_ids: null`.\n* **Channel-specific access:**\n  * Provide a `channel_ids` array containing the channels accessible by the customer. This array cannot be empty."
      summary: BigCommerce Create Customers
      tags:
      - Customers
      operationId: createCustomers
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/customer_Post'
            examples:
              example-1:
                value:
                - email: string@example.com
                  first_name: string
                  last_name: string
                  company: string
                  phone: string
                  notes: string
                  tax_exempt_category: string
                  customer_group_id: 0
                  addresses:
                  - address1: Addr 1
                    address2: ''
                    address_type: residential
                    city: San Francisco
                    company: History
                    country_code: US
                    first_name: Ronald
                    last_name: Swimmer
                    phone: '707070707'
                    postal_code: '33333'
                    state_or_province: California
                    form_fields:
                    - name: test
                      value: test
                  authentication:
                    force_password_reset: true
                    new_password: string123
                  accepts_product_review_abandoned_cart_emails: true
                  store_credit_amounts:
                  - amount: 43.15
                  origin_channel_id: 1
                  channel_ids:
                  - 1
                  form_fields:
                  - name: test
                    value: test
        required: true
        x-examples: {}
        description: ''
      responses:
        '200':
          $ref: '#/components/responses/CustomerCollectionResponse'
        '413':
          description: The request payload is too large. The maximum number of items allowed in the array is 10.
        '422':
          description: The *Customer* was not valid. This is the result of missing required fields or trying to edit a read only field. See the response for more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    status: 422
                    title: Create customers failed.
                    type: /api-docs/getting-started/api-status-codes
                    errors:
                      .customer_create: Error creating customers
    put:
      description: 'Updates Customers. Subresource updates are not supported. Up to 10 customers can be updated in one call.


        **Required Fields**

        * id -- ID of the *Customer* This must be included in the request body


        **Read Only Fields**

        * id

        * registration_ip_address

        * date_created

        * date_modified



        **Notes**


        * Attributes Values can not be updated using Update a Customer. Use the [Update customer attribute values](/docs/rest-management/customers/customer-attribute-values#upsert-customer-attribute-values) endpoint.

        * channel_ids -- Updating the list of channels a customer can access may create some side effects in a multi-storefront situation. This list determines which customer account we will use to authenticate a shopper given a channel.'
      summary: BigCommerce Update Customers
      tags:
      - Customers
      operationId: updateCustomers
      deprecated: false
      responses:
        '200':
          $ref: '#/components/responses/CustomerCollectionResponse'
        '413':
          description: The request payload is too large. The maximum number of items allowed in the array is 10.
        '422':
          description: 'The `Customer` 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'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/customer_Put'
            examples:
              example-1:
                value:
                - email: string
                  first_name: string
                  last_name: string
                  company: string
                  phone: string
                  registration_ip_address: string
                  notes: string
                  tax_exempt_category: string
                  customer_group_id: 0
                  id: 1
                  authentication:
                    force_password_reset: true
                    new_password: string123
                  accepts_product_review_abandoned_cart_emails: true
                  store_credit_amounts:
                  - amount: 43.15
                  origin_channel_id: 1
                  channel_ids:
                  - 1
                  form_fields:
                  - name: test
                    value: test
              example-2-form-fields:
                value:
                - id: 1
                  form_fields:
                  - name: test
                    value: test
    delete:
      description: 'Deletes Customers.


        **Required Query**

        * id:in -- ID of the customer


        **Notes**


        A query is required to delete customers. If not provided, a 204 is returned, with no changes to the data.'
      summary: BigCommerce Delete Customers
      tags:
      - Customers
      operationId: deleteCustomers
      deprecated: false
      parameters:
      - in: query
        name: id:in
        description: 'Filter items by ID.

          `id:in=4,5,6`'
        required: true
        style: form
        explode: false
        schema:
          type: array
          items:
            type: integer
      responses:
        '204':
          description: ''
          headers: {}
components:
  responses:
    CustomerCollectionResponse:
      description: Customer Collection Response
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/customer_Full'
              meta:
                $ref: '#/components/schemas/_metaCollection'
          examples:
            example-1:
              value:
                data:
                - email: string@example.com
                  first_name: string
                  last_name: string
                  company: string
                  phone: string
                  notes: string
                  tax_exempt_category: string
                  customer_group_id: 0
                  addresses:
                  - first_name: string
                    last_name: string
                    address1: Addr1
                    address2: ''
                    city: string
                    state_or_province: string
                    postal_code: string
                    country_code: st
                    phone: string
                    address_type: residential
                    customer_id: 0
                    id: 0
                    country: string
                  store_credit_amounts:
                  - amount: 43.15
                  accepts_product_review_abandoned_cart_emails: true
                  channel_ids:
                  - 1
                  shopper_profile_id: 82511e54-4040-40fe-b742-2b25655f205b
                  segment_ids:
                  - 5bb733a9-5491-47b3-9451-9ae8d6a6bc6b
                meta:
                  pagination:
                    total: 0
                    count: 0
                    per_page: 0
                    current_page: 0
                    total_pages: 0
                    links:
                      previous: string
                      current: string
                      next: string
  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
    customerAttributes_Base:
      description: ''
      title: customerAttributes_Base
      type: object
      properties:
        attribute_id:
          type: integer
          format: int32
          example: 55
          description: Attribute ID.
        attribute_value:
          type: string
          example: string
          minLength: 0
          maxLength: 255
          description: Attribute value. This will always be a string, regardless of the attribute’s type.
      x-internal: false
    CustomerStoredCreditAmounts:
      description: 'Store credit. '
      type: array
      format: double
      items:
        type: object
        properties:
          amount:
            type: number
            format: float
            example: 43.15
      x-internal: false
    customer_Post:
      title: customer_Post
      type: object
      properties:
        email:
          description: The email of the customer. Must be unique.
          type: string
          minLength: 3
          maxLength: 255
        first_name:
          description: The first name of the customer.
          type: string
          minLength: 1
          maxLength: 100
        last_name:
          description: The last name of the customer.
          type: string
          minLength: 1
          maxLength: 100
        company:
          description: The company of the customer.
          type: string
          minLength: 0
          maxLength: 255
        phone:
          description: The phone number of the customer.
          type: string
          minLength: 0
          maxLength: 50
        notes:
          description: The customer notes.
          type: string
        tax_exempt_category:
          description: The tax exempt category code for the customer.
          type: string
          minLength: 0
          maxLength: 255
        customer_group_id:
          description: ID of the group which this customer belongs to.
          type: integer
          format: int32
        addresses:
          description: Array of customer addresses. Limited to 10.
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/customerAddresses_CustomerPost'
        attributes:
          description: Array of customer attributes. Limited to 10.
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/customerAttributes_Base'
        authentication:
          $ref: '#/components/schemas/customerAuthentication_PostPut'
        accepts_product_review_abandoned_cart_emails:
          type: boolean
          description: It determines if the customer is signed up to receive either product review or abandoned cart emails or receive both emails.
        store_credit_amounts:
          $ref: '#/components/schemas/CustomerStoredCreditAmounts'
        origin_channel_id:
          type: integer
          description: Channel ID of the customer that has created the form.
        channel_ids:
          description: Array of channels the customer can access.
          type: array
          example:
          - 1
          - 2
          items:
            type: integer
        form_fields:
          type: array
          description: 'Array of form fields. Controlled by formfields parameter.

            '
          items:
            $ref: '#/components/schemas/formFieldValue'
      required:
      - email
      - first_name
      - last_name
      x-internal: false
    customerChannelIds:
      type: array
      title: customerChannelIds
      description: Array of channel ids the Customer has access to.
      items:
        example:
        - 1
        - 2
      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
    customer_Put:
      title: customer_Put
      type: object
      properties:
        email:
          description: The email of the customer. Must be unique.
          type: string
          minLength: 3
          maxLength: 255
        first_name:
          description: The first name of the customer.
          type: string
          minLength: 1
          maxLength: 100
        last_name:
          description: The last name of the customer.
          type: string
          minLength: 1
          maxLength: 100
        company:
          description: The company of the customer.
          type: string
          minLength: 0
          maxLength: 255
        phone:
          description: The phone number of the customer.
          type: string
          minLength: 0
          maxLength: 50
        registration_ip_address:
          description: The IP address from which this customer was registered.
          type: string
          minLength: 0
          maxLength: 30
        notes:
          description: The customer notes.
          type: string
        tax_exempt_category:
          description: The tax exempt category code for the customer.
          type: string
          minLength: 0
          maxLength: 255
        customer_group_id:
          description: ID of the group which this customer belongs to.
          type: integer
          format: int32
        id:
          description: The unique numeric ID of the customer.
          type: integer
          format: int32
        authentication:
          $ref: '#/components/schemas/customerAuthentication_PostPut'
        accepts_product_review_abandoned_cart_emails:
          type: boolean
          description: It determines if the customer is signed up to receive either product review or abandoned cart emails or receive both emails.
        store_credit_amounts:
          $ref: '#/components/schemas/CustomerStoredCreditAmounts'
        origin_channel_id:
          type: integer
          description: Channel ID of the customer that has created the form.
        channel_ids:
          description: Arrays of channels the customer can access.
          type: array
          items:
            type: integer
        form_fields:
          type: array
          description: 'Array of form fields. Controlled by formfields parameter.

            '
          items:
            $ref: '#/components/schemas/formFieldValue'
      required:
      - id
      x-internal: false
    customerAddresses_CustomerPost:
      title: customerAddresses_CustomerPost
      example:
        address1: Addr 1
        address2: ''
        address_type: residential
        city: San Francisco
        company: History
        country_code: US
        first_name: Ronald
        last_name: Swimmer
        phone: '707070707'
        postal_code: '33333'
        state_or_province: California
        form_fields:
        - name: test
          value: test
      type: object
      properties:
        first_name:
          description: The first name associated with 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. Required for countries in which valid addresses must contain a state/province.
          type: string
          minLength: 0
          maxLength: 100
        postal_code:
          description: The postal code of the customer address. Required for countries in which valid addresses must have postal codes.
          type: string
          minLength: 0
          maxLength: 30
        country_code:
          description: The country code of the customer address.
          type: string
          minLength: 2
          maxLength: 2
        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
        form_fields:
          description: Array of form fields. Controlled by `formfields` parameter.
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/formFieldValue'
            title: Customer Address Form Field Value
      required:
      - first_name
      - last_name
      - address1
      - city
      - country_code
      description: The `address` object for the `customer` objectʼs `addresses` array.
      x-internal: false
    customerAuthentication_PostPut:
      title: customerAuthentication_PostPut
      allOf:
      - properties:
          force_password_reset:
            description: If `true`, this customer will be forced to change password on next login.
            type: boolean
      - properties:
          new_password:
            description: New password for customer. Write only field.
            type: string
      type: object
      x-internal: false
    customer_Full:
      title: customer_Full
      type: object
      properties:
        email:
          description: The email of the customer. Must be unique.
          type: string
          minLength: 3
          maxLength: 255
        first_name:
          description: The first name of the customer.
          type: string
          minLength: 1
          maxLength: 100
        last_name:
          description: The last name of the customer.
          type: string
          minLength: 1
          maxLength: 100
        company:
          description: The company of the customer.
          type: string
          minLength: 0
          maxLength: 255
        phone:
          description: The phone number of the customer.
          type: string
          minLength: 0
          maxLength: 50
        registration_ip_address:
          description: The IP address from which this customer was registered.
          type: string
          minLength: 0
          maxLength: 30
        notes:
          description: The customer notes.
          type: string
        tax_exempt_category:
          description: The tax exempt category code for the customer.
          type: string
          minLength: 0
          maxLength: 255
        customer_group_id:
          description: ID of the group which this customer belongs to.
          type: integer
          format: int32
        id:
          description: The unique numeric ID of the customer.
          type: integer
          format: int32
        date_modified:
          description: The date on which the customer was modified.
          type: string
          format: date-time
        date_created:
          description: The date of which the customer was created.
          type: string
          format: date-time
        address_count:
          description: Total number of customer addresses.
          type: integer
          format: int32
        attribute_count:
          description: Total number of customer attributes.
          type: integer
          format: int32
        authentication:
          title: Customer Authentication Base
          example:
            force_password_reset: true
          type: object
          properties:
            force_password_reset:
              description: If `true`, this customer will be forced to change password on next login.
              type: boolean
        addresses:
          description: Array of customer addresses. Limited to 10.
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/address_Full'
        attributes:
          description: Array of customer attributes. Limited to 10.
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/attribute_Full'
        form_fields:
          description: Array of form fields. Controlled by `formfields` parameter.
          type: array
          items:
            $ref: '#/components/schemas/formFieldValue_Customer'
        store_credit_amounts:
          $ref: '#/components/schemas/CustomerStoredCreditAmounts'
        accepts_product_review_abandoned_cart_emails:
          type: boolean
          description: Determines if the customer is signed up to receive either product review or abandoned cart emails or receive both emails.
        origin_channel_id:
          type: integer
          description: Channel ID of the customer that has created the form.
        channel_ids:
          $ref: '#/components/schemas/customerChannelIds'
      x-internal: false
    address_Full:
      title: address_Full
      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
        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
        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
        customer_id:
          description: The customer ID.
          type: integer
          format: int32
        id:
          description: The unique numeric ID of the address.
          type: integer
          format: int32
        country:
          description: The country name of the customer address.
          type: string
        form_fields:
          description: Array of form fields. Controlled by `formfields` parameter.
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/formFieldValue'
            title: Customer Address Form Field Value
      required:
      - first_name
      - last_name
      - address1
      - city
      - state_or_province
      - postal_code
      - country_code
      - customer_id
      - id
      x-internal: false
    attribute_Full:
      description: ''
      type: object
      x-examples:
        Example:
          attribute_id: 2
          attribute_value: 'Yes'
          customer_id: 1
          date_created: '2021-07-28T19:00:38Z'
          date_modified: '2021-07-28T19:00:38Z'
          id: 2
      properties:
        attribute_id:
          type: integer
          description: Attribute ID.
          format: int32
          example: 2
        attribute_value:
          type: string
          minLength: 1
          description: Attribute value.
          example: 'Yes'
        customer_id:
          type: integer
          description: Customer ID.
          example: 1
          format: int32
        date_created:
          type: string
          minLength: 1
          description: The date the customer attribute was created.
          format: date-time
        date_modified:
          type: string
          minLength: 1
          description: The date the customer attribute was modified.
          format: date-time
        id:
          type: integer
          description: Attribute value ID.
          format: int32
          example: 2
      x-internal: false
    Pagination:
      title: Pagination
      description: Da

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/bigcommerce-customers-api-openapi.yml
BigCommerce Customers API

Documentation

Specifications

Other Resources

OpenAPI Specification
