BigCommerce Customer Management
Before writing code
Fetch live docs:
- Web-search
site:developer.bigcommerce.com rest customers for Customers API reference
- Fetch
https://docs.bigcommerce.com/developer/docs/storefront/guides/customer-authentication/customer-login for Customer Login API
- Web-search
bigcommerce customer groups api for customer group management
Customer API (V3)
Endpoints
| Endpoint |
Methods |
Description |
/v3/customers |
GET, POST, PUT, DELETE |
Customer CRUD |
/v3/customers/addresses |
GET, POST, PUT, DELETE |
Customer addresses |
/v3/customers/attributes |
GET, POST, PUT, DELETE |
Custom attribute definitions |
/v3/customers/attribute-values |
GET, PUT, DELETE |
Attribute values per customer |
/v3/customers/form-field-values |
GET, PUT |
Form field values |
/v3/customers/settings |
GET, PUT |
Customer settings |
Customer Fields
Core fields:
id, email, first_name, last_name, company
phone, date_created, date_modified
customer_group_id — assigned group
notes — admin notes
registration_ip_address
authentication — password or external auth
Creating Customers
POST /v3/customers
[{
"email": "customer@example.com",
"first_name": "Jane",
"last_name": "Doe",
"authentication": {
"new_password": "SecurePassword123!"
}
}]
Note: V3 accepts arrays — batch create/update multiple customers at once.
Customer Groups
What They Do
Segment customers for pricing, access, and promotions:
- Price Lists — group-specific pricing
- Category Access — restrict category visibility by group
- Promotions — group-specific discounts
- Tax Exemptions — tax-exempt groups
Managing Groups
GET /v2/customer_groups — list groups
POST /v2/customer_groups — create group
- Assign customers via
customer_group_id field on customer
Default Groups
| Group |
Description |
| Guest |
Non-logged-in visitors |
| Default |
Default for new customers |
| Custom groups |
Merchant-defined segments |
Customer Addresses
CRUD Operations
POST /v3/customers/addresses
[{
"customer_id": 123,
"first_name": "Jane",
"last_name": "Doe",
"address1": "123 Main St",
"city": "Austin",
"state_or_province": "Texas",
"postal_code": "78701",
"country_code": "US",
"address_type": "residential"
}]
Custom Attributes
Attribute Definitions
Create custom fields for customer profiles:
POST /v3/customers/attributes
[{
"name": "Loyalty Tier",
"type": "string"
}]
Types: string, number, date, dropdown
Attribute Values
Set per customer:
PUT /v3/customers/attribute-values
[{
"customer_id": 123,
"attribute_id": 1,
"value": "Gold"
}]
Customer Login API (SSO)
How It Works
Log customers into BigCommerce storefront from an external system:
- Generate a JWT token on your server with customer info
- Sign with your Client Secret
- Redirect customer to
https://{store_url}/login/token/{jwt}
- BigCommerce validates the JWT and creates a session
JWT Payload
{
"iss": "your_client_id",
"iat": 1706140800,
"jti": "unique-request-id",
"operation": "customer_login",
"store_hash": "abc123",
"customer_id": 456,
"redirect_to": "/account",
"channel_id": 1
}
Sign with HMAC-SHA256 using your Client Secret.
Use Cases
- Single Sign-On (SSO) from your own auth system
- Deep linking logged-in customers into their BigCommerce account
- Headless storefronts using external authentication
Customer Impersonation (GraphQL)
For accessing customer-specific data in the GraphQL Storefront API:
- Create impersonation token:
POST /v3/storefront/api-token-customer-impersonation
- Send with
X-Bc-Customer-Id: {customer_id} header
- Access wishlists, order history, saved addresses in GraphQL
Querying Customers
V3 Filters
id:in=1,2,3 — by IDs
email:in=a@b.com,c@d.com — by emails
name:like=Jane — name search
customer_group_id:in=5,6 — by group
date_created:min=2024-01-01 — date range
include=addresses,attributes — include sub-resources
Best Practices
- Use V3 Customers API for all new development
- Batch operations — V3 accepts arrays for create/update
- Use customer groups for segmentation and pricing tiers
- Use custom attributes for integration data (not notes)
- Implement SSO via Customer Login API for seamless cross-platform auth
- Validate email addresses before creating customers
- Handle duplicate email addresses gracefully (BigCommerce enforces unique emails)
- Use customer impersonation tokens for personalized GraphQL queries
Fetch the BigCommerce Customers API reference and Customer Login API documentation for exact endpoints, JWT format, and attribute types before implementing.
1---2name: bc-customers3description: Work with BigCommerce customers — Customer API, customer groups, addresses, stored instruments, attributes, Customer Login API (SSO), and customer segmentation. Use when building customer-facing features or integrating customer data.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/bc-customers7---89# BigCommerce Customer Management1011## Before writing code1213**Fetch live docs**:141. Web-search `site:developer.bigcommerce.com rest customers` for Customers API reference152. Fetch `https://docs.bigcommerce.com/developer/docs/storefront/guides/customer-authentication/customer-login` for Customer Login API163. Web-search `bigcommerce customer groups api` for customer group management1718## Customer API (V3)1920### Endpoints2122| Endpoint | Methods | Description |23|----------|---------|-------------|24| `/v3/customers` | GET, POST, PUT, DELETE | Customer CRUD |25| `/v3/customers/addresses` | GET, POST, PUT, DELETE | Customer addresses |26| `/v3/customers/attributes` | GET, POST, PUT, DELETE | Custom attribute definitions |27| `/v3/customers/attribute-values` | GET, PUT, DELETE | Attribute values per customer |28| `/v3/customers/form-field-values` | GET, PUT | Form field values |29| `/v3/customers/settings` | GET, PUT | Customer settings |3031### Customer Fields3233Core fields:34- `id`, `email`, `first_name`, `last_name`, `company`35- `phone`, `date_created`, `date_modified`36- `customer_group_id` — assigned group37- `notes` — admin notes38- `registration_ip_address`39- `authentication` — password or external auth4041### Creating Customers4243```json44POST /v3/customers45[{46 "email": "customer@example.com",47 "first_name": "Jane",48 "last_name": "Doe",49 "authentication": {50 "new_password": "SecurePassword123!"51 }52}]53```5455Note: V3 accepts arrays — batch create/update multiple customers at once.5657## Customer Groups5859### What They Do6061Segment customers for pricing, access, and promotions:62- **Price Lists** — group-specific pricing63- **Category Access** — restrict category visibility by group64- **Promotions** — group-specific discounts65- **Tax Exemptions** — tax-exempt groups6667### Managing Groups6869- `GET /v2/customer_groups` — list groups70- `POST /v2/customer_groups` — create group71- Assign customers via `customer_group_id` field on customer7273### Default Groups7475| Group | Description |76|-------|-------------|77| Guest | Non-logged-in visitors |78| Default | Default for new customers |79| Custom groups | Merchant-defined segments |8081## Customer Addresses8283### CRUD Operations8485```json86POST /v3/customers/addresses87[{88 "customer_id": 123,89 "first_name": "Jane",90 "last_name": "Doe",91 "address1": "123 Main St",92 "city": "Austin",93 "state_or_province": "Texas",94 "postal_code": "78701",95 "country_code": "US",96 "address_type": "residential"97}]98```99100## Custom Attributes101102### Attribute Definitions103104Create custom fields for customer profiles:105```json106POST /v3/customers/attributes107[{108 "name": "Loyalty Tier",109 "type": "string"110}]111```112113Types: `string`, `number`, `date`, `dropdown`114115### Attribute Values116117Set per customer:118```json119PUT /v3/customers/attribute-values120[{121 "customer_id": 123,122 "attribute_id": 1,123 "value": "Gold"124}]125```126127## Customer Login API (SSO)128129### How It Works130131Log customers into BigCommerce storefront from an external system:1321. Generate a JWT token on your server with customer info1332. Sign with your Client Secret1343. Redirect customer to `https://{store_url}/login/token/{jwt}`1354. BigCommerce validates the JWT and creates a session136137### JWT Payload138139```json140{141 "iss": "your_client_id",142 "iat": 1706140800,143 "jti": "unique-request-id",144 "operation": "customer_login",145 "store_hash": "abc123",146 "customer_id": 456,147 "redirect_to": "/account",148 "channel_id": 1149}150```151152Sign with HMAC-SHA256 using your Client Secret.153154### Use Cases155156- Single Sign-On (SSO) from your own auth system157- Deep linking logged-in customers into their BigCommerce account158- Headless storefronts using external authentication159160## Customer Impersonation (GraphQL)161162For accessing customer-specific data in the GraphQL Storefront API:163- Create impersonation token: `POST /v3/storefront/api-token-customer-impersonation`164- Send with `X-Bc-Customer-Id: {customer_id}` header165- Access wishlists, order history, saved addresses in GraphQL166167## Querying Customers168169### V3 Filters170171- `id:in=1,2,3` — by IDs172- `email:in=a@b.com,c@d.com` — by emails173- `name:like=Jane` — name search174- `customer_group_id:in=5,6` — by group175- `date_created:min=2024-01-01` — date range176- `include=addresses,attributes` — include sub-resources177178## Best Practices179180- Use V3 Customers API for all new development181- Batch operations — V3 accepts arrays for create/update182- Use customer groups for segmentation and pricing tiers183- Use custom attributes for integration data (not notes)184- Implement SSO via Customer Login API for seamless cross-platform auth185- Validate email addresses before creating customers186- Handle duplicate email addresses gracefully (BigCommerce enforces unique emails)187- Use customer impersonation tokens for personalized GraphQL queries188189Fetch the BigCommerce Customers API reference and Customer Login API documentation for exact endpoints, JWT format, and attribute types before implementing.