BigCommerce User Management API Guide

Auth method: OAuth 2.0 (API key / access token via X-Auth-Token header)

Setup steps

1. Log in to the BigCommerce control panel and navigate to Settings > API > API Accounts.
2. Click 'Create API Account' and select 'V2/V3 API Token'.
3. Set the required OAuth scopes (e.g., Customers: read-only or modify).
4. Copy the generated Client ID, Client Secret, and Access Token.
5. Include the Access Token in all API requests as the header: X-Auth-Token: {access_token}.

Required scopes

List Customers

• Method: GET
• URL: https://api.bigcommerce.com/stores/{store_hash}/v3/customers
• Watch out for: Supports filtering by email, name, customer_group_id, date_created, date_modified. Use ?email:in=a@b.com for exact email lookup.

Request example

GET /stores/{store_hash}/v3/customers?limit=50&page=1
X-Auth-Token: {access_token}
Accept: application/json

Response example

{
  "data": [{"id":1,"email":"jane@example.com","first_name":"Jane","last_name":"Doe"}],
  "meta": {"pagination":{"total":1,"count":1,"per_page":50,"current_page":1,"total_pages":1}}
}

Get Customer by ID

• Method: GET
• URL: https://api.bigcommerce.com/stores/{store_hash}/v3/customers?id:in={customer_id}
• Watch out for: V3 does not have a single GET /customers/{id} endpoint; use the ?id:in= filter instead.

Request example

GET /stores/{store_hash}/v3/customers?id:in=42
X-Auth-Token: {access_token}

Response example

{
  "data": [{"id":42,"email":"jane@example.com","first_name":"Jane","last_name":"Doe"}],
  "meta": {}
}

Create Customer(s)

• Method: POST
• URL: https://api.bigcommerce.com/stores/{store_hash}/v3/customers
• Watch out for: Request body must be an array even for a single customer. Batch create up to 10 customers per request.

Request example

POST /stores/{store_hash}/v3/customers
X-Auth-Token: {access_token}
Content-Type: application/json

[{"email":"new@example.com","first_name":"New","last_name":"User","authentication":{"new_password":"Passw0rd!"}}]

Response example

{
  "data": [{"id":101,"email":"new@example.com","first_name":"New","last_name":"User"}],
  "meta": {}
}

Update Customer(s)

• Method: PUT
• URL: https://api.bigcommerce.com/stores/{store_hash}/v3/customers
• Watch out for: Uses PUT (not PATCH) for updates. The id field is required in each object. Batch update up to 10 customers per request.

Request example

PUT /stores/{store_hash}/v3/customers
X-Auth-Token: {access_token}
Content-Type: application/json

[{"id":101,"first_name":"Updated","last_name":"Name"}]

Response example

{
  "data": [{"id":101,"email":"new@example.com","first_name":"Updated","last_name":"Name"}],
  "meta": {}
}

Delete Customer(s)

• Method: DELETE
• URL: https://api.bigcommerce.com/stores/{store_hash}/v3/customers?id:in={id1},{id2}
• Watch out for: Requires at least one filter (id:in). Deleting a customer is permanent and removes all associated data.

Request example

DELETE /stores/{store_hash}/v3/customers?id:in=101,102
X-Auth-Token: {access_token}

Response example

HTTP 204 No Content

List/Create Customer Addresses

• Method: GET
• URL: https://api.bigcommerce.com/stores/{store_hash}/v3/customers/addresses
• Watch out for: Addresses are a separate sub-resource. POST to the same endpoint with an array to create addresses.

Request example

GET /stores/{store_hash}/v3/customers/addresses?customer_id:in=42
X-Auth-Token: {access_token}

Response example

{
  "data": [{"id":5,"customer_id":42,"first_name":"Jane","address1":"123 Main St","city":"Austin","state_or_province":"TX","country_code":"US"}],
  "meta": {}
}

Generate Customer Login Token

• Method: POST
• URL: https://api.bigcommerce.com/stores/{store_hash}/v2/customers/{customer_id}/login_token
• Watch out for: Requires the store/v2/customers/login scope. Token is a short-lived JWT for storefront SSO login. This is a V2 endpoint.

Request example

POST /stores/{store_hash}/v2/customers/42/login_token
X-Auth-Token: {access_token}

Response example

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

List Customer Attribute Values

• Method: GET
• URL: https://api.bigcommerce.com/stores/{store_hash}/v3/customers/attribute-values
• Watch out for: Custom attribute definitions must be created first via POST /v3/customers/attributes before values can be assigned.

Request example

GET /stores/{store_hash}/v3/customers/attribute-values?customer_id:in=42
X-Auth-Token: {access_token}

Response example

{
  "data": [{"customer_id":42,"attribute_id":3,"attribute_value":"VIP","id":7}],
  "meta": {}
}

• Rate limits: BigCommerce enforces per-store rate limits on API requests. Standard stores are limited to 150 requests per 30-second rolling window. Enterprise stores may have higher limits negotiated. Rate limit status is communicated via response headers.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: Headers include X-Rate-Limit-Requests-Left, X-Rate-Limit-Requests-Quota, X-Rate-Limit-Time-Reset-Ms, and X-Rate-Limit-Time-Window-Ms. When limit is exceeded, a 429 response is returned with a Retry-After header.
• Pagination method: offset
• Default page size: 50
• Max page size: 250
• Pagination pointer: page / limit

• Webhooks available: Yes
• Webhook notes: BigCommerce supports webhooks for customer lifecycle events. Webhooks are registered via the Webhooks API and deliver HTTP POST payloads to a configured destination URL.
• Alternative event strategy: Polling the GET /v3/customers endpoint with date_modified:min filter can be used as a fallback if webhooks are not feasible.
• Webhook events: store/customer/created, store/customer/updated, store/customer/deleted, store/customer/address/created, store/customer/address/updated, store/customer/address/deleted, store/customer/payment/instrument/default/updated

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise
• Endpoint: Not documented

Limitations:

• BigCommerce does not offer a native SCIM 2.0 endpoint.
• SCIM-like provisioning can be achieved via third-party middleware (e.g., miniOrange, LoginRadius) that maps SCIM calls to BigCommerce REST API calls.
• Okta integration for SSO is available but uses a custom app connector, not native SCIM.
• Microsoft Entra ID and OneLogin integrations are available via third-party connectors only.

Three integration patterns cover the majority of production use cases. For provisioning, POST to /v3/customers with an array body including email, first_name, last_name, and `authentication.

new_password; passwords are never returned in subsequent GET calls, so store them externally at creation time. For sync, register a store/customer/updatedwebhook via/v2/hooks- payloads contain only minimal identifiers, so a follow-up GET to/v3/customers?

id:in={id}is always required to retrieve full customer data. For storefront SSO, POST to the V2-only/v2/customers/{customer_id}/login_tokenendpoint (requiresstore/v2/customers/loginscope) and redirect the user to/login/token/{jwt}` immediately - the JWT is short-lived and single-use.

Rate limits apply across all patterns: Standard, Plus, and Pro stores are capped at 150 requests per 30-second rolling window; monitor X-Rate-Limit-Requests-Left and handle HTTP 429 with Retry-After backoff.

Provision a new customer account with a password

1. Obtain an API access token with store/v2/customers (modify) scope from the BigCommerce control panel.
2. POST to /v3/customers with an array containing the new customer object including email, first_name, last_name, and authentication.new_password.
3. Parse the response to retrieve the auto-generated customer id.
4. Optionally POST to /v3/customers/addresses to add a default address for the new customer.
5. Optionally POST to /v3/customers/attribute-values to set any custom attributes.

Watch out for: The request body must be a JSON array even for a single customer. Passwords are never returned in subsequent GET calls.

Sync customer updates from an external system

1. Register a webhook for store/customer/updated via POST to /v2/hooks with the destination URL.
2. On webhook receipt, extract the customer id from the payload.
3. GET /v3/customers?id:in={id} to fetch the latest customer data.
4. Apply business logic and if needed PUT /v3/customers with updated fields (id required in body).
5. If webhooks are unavailable, poll GET /v3/customers?date_modified:min={last_sync_timestamp} on a schedule.

Watch out for: Webhook payloads contain minimal data (store_id, producer, scope, data.id); a follow-up GET is always required to retrieve full customer details.

Implement storefront SSO (customer login)

1. Ensure the API account has the store/v2/customers/login scope.
2. When a user authenticates in your external system, POST to /v2/customers/{customer_id}/login_token.
3. Receive the short-lived JWT token in the response.
4. Redirect the user to https://{store_domain}/login/token/{jwt_token} on the BigCommerce storefront.
5. The customer is automatically logged in to the storefront session.

Watch out for: The login token JWT is short-lived. It must be used immediately after generation. This endpoint is V2 only and requires the customer to already exist in BigCommerce.

Several non-obvious behaviors cause integration failures in production. The V3 API has no GET /v3/customers/{id} endpoint - single-customer lookup requires the ?id:in={id} filter pattern. Updates use PUT (not PATCH), and the id field must be present in every object in the batch array.

Deletes require at least one filter parameter (id:in) and are irreversible, cascading to all associated customer data. Custom attributes follow a two-step process: the attribute definition must be created via POST /v3/customers/attributes before values can be assigned to any customer.

On multi-storefront stores, omitting channel_ids during customer creation can render the customer invisible on non-default channels. Finally, V2 and V3 endpoints coexist with overlapping but non-identical capabilities - the login token endpoint is V2-only, while attribute management is V3-only, so integrations frequently need to call both API versions.