orcaqubits/bc-customers

BigCommerce Customer Management

Before writing code

Fetch live docs:

1. Web-search site:developer.bigcommerce.com rest customers for Customers API reference
2. Fetch https://developer.bigcommerce.com/docs/start/authentication/customer-login for Customer Login API
3. 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": "[email protected]",
  "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:

1. Generate a JWT token on your server with customer info
2. Sign with your Client Secret
3. Redirect customer to https://{store_url}/login/token/{jwt}
4. 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:[email protected],[email protected] — 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.