Managing customers
This section covers different ways to associate customers with headless carts.
GraphQL Storefront API
You can use the GraphQL Storefront API to sign in to a customer account using hosted client-side, headless client-side, or server-side code.
Hosted client-side sign-in
To sign into a customer account with an email address and a password in client-side code on a hosted storefront, use the login mutation.
When you sign in a customer using the login mutation, subsequent queries to the GraphQL Storefront API will return customer-specific results, such as customer group pricing.
Headless and server-side sign-in
To make queries from the perspective of a particular customer using headless or server-side code, use customer access tokens and storefront tokens. Then, use the customer access token in the X-Bc-Customer-Access-Token header.
We recommend using the login mutation and customer access token because this combination is more secure. In addition, there is a seamless redirection and synchronization between headless storefronts and hosted checkouts, which allow for transferring session details, such as customer and cart data, across various contexts.
Customer single sign-on
If using the customer access token, then you just need to use the createCartRedirectUrls mutation and use the redirectUrl provided there. It will be a session sync link that will copy data from the headless storefront to the BigCommerce-hosted page. This approach simplifies session synchronization and offers consistent login states.
mutation createRedirectUrl($input: CreateCartRedirectUrlsInput!) {
cart {
createCartRedirectUrls(input: $input) {
redirectUrls {
redirectedCheckoutUrl
}
}
}
}The other option is when a customer signs in to your headless storefront and your application redirects them to a BigCommerce-hosted page, such as checkout, you can use the Customer Login API to sign them in to the hosted session.
You can sign a customer in to an embedded checkout by using the session-sync URL from the createCartRedirectUrls mutation (opens in a new tab).
{
"iss": {{CLIENT_ID}},
"iat": 1535393113,
"jti": {{UUID}},
"operation": "customer_login",
"store_hash": {{STORE_HASH}},
"customer_id": {{CUSTOMER_ID}},
"channel_id": {{CHANNEL_ID}},
"redirect_to": "/cart.php?embedded=1&action=loadInCheckout&id=bc218c65-7a32-4ab7-8082-68730c074d02&token=aa958e2b7922035bf3339215d95d145ebd9193deb36ae847caa780aa2e003e4b",
"request_ip": "111.222.333.444"
}Identifying signed-in customers
If a customer signs in to a BigCommerce-hosted cart or checkout, then navigates back to the headless storefront, you will need to confirm the customer's identity before revealing sensitive information.
To address this need, BigCommerce provides the Current Customer API, which you can access using client-side JavaScript. The Get current customer endpoint returns a BigCommerce-generated JWT signed with the client secret of the API account you used to make the request. To access customer details, such as customer ID, customer group number, and email, use a library to decode the JWT.
Create a session sync JWT token
The session sync token is a JWT (JSON Web Token) designed to seamlessly synchronize user sessions across different storefront environments—whether between headless and Stencil, Stencil and Stencil, or headless and headless setups. You can generate this token using the generateSessionSyncJwt (opens in a new tab) GraphQL mutation.
The token enables secure, transparent, and optional sharing of session-related data, including:
- customer login data
- cart data
- visit data for analytics
One key use of the session sync token is to enable smooth redirection to any page. This works for both logged-in customers and anonymous shoppers. To support this, the token can include a redirect_to field in its payload. After validating the token, this field is used to redirect the shopper to the appropriate page (e.g., checkout), carrying over all necessary session context.
POST https://api.bigcommerce.com/stores/{store_hash}/graphql
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
Authorization: {{Bearer token}}
mutation sessionSyncJwt(
$redirectTo: String!,
$cartId: String,
$visitId: UUID,
$visitorId: UUID,
$ipAddress: IpAddress,
$paymentWalletData: PaymentWalletDataInput
) {
generateSessionSyncJwt(
redirectTo: $redirectTo
visitorId: $visitorId
visitId: $visitId
cartId: $cartId
paymentWalletData: $paymentWalletData
ipAddress: $ipAddress
) {
result {
token
url
}
errors {
...on Error {
message
}
}
}
}
{
"redirectTo": "xyz789",
"cartId": "abc123",
"visitorId": "3d077ee5-373a-42aa-91d2-dd43dc87dde9",
"ipAddress": IpAddress,
"paymentWalletData": PaymentWalletDataInput,
"visitId": "3d077ee5-373a-42aa-91d2-dd43dc87dde9"
}Surfacing customer group pricing
When querying the GraphQL Storefront API, customer-specific pricing will be reflected in query results if the request is made using a customer access token.
For server-side REST implementations, you can use the REST Management API pricing feature to Get prices for a particular customer group.
POST https://api.bigcommerce.com/stores/{store_hash}/v3/pricing/products
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
{
"channel_id": 1,
"currency_code": "USD",
"customer_group_id": 0,
"items": [
{
"product_id": 0,
"variant_id": 0,
"options": [
{
"option_id": 0,
"value_id": 0
}
]
}
]
}