Shopper Context Lite

Shopper Context Lite uses the sfdc_shopper_context request header to apply a lightweight subset of shopper context to personalized Shopper API requests. A headless storefront can start personalized requests immediately, without first creating shopper context and waiting for the response.

Use Shopper Context Lite for context that a storefront knows when a shopper arrives, such as an IP address, source code, or limited storefront-specific qualifiers. For context such as customer groups, coupon codes, assignment qualifiers, effective dates, and geolocation, use the Shopper Context API. Shopper Context Lite complements the Shopper Context API and doesn’t replace it.

Benefits

Applies personalization on the first personalized Shopper API request, without a preceding context update.
Removes the client-side waterfall for the supported properties.
Preserves other stored shopper context when lite values are merged.
Uses a compact, bounded payload.
Is optional and backward compatible. Requests without the header use the stored shopper context.
Doesn’t require an additional OAuth scope.

Before You Begin

Obtain a Shopper Login and API Access Service (SLAS) shopper access token that authorizes the Shopper API request. The token provides the unique shopper ID (USID) that B2C Commerce uses to associate stored shopper context with the shopper.

Shopper Context Lite doesn’t require an additional OAuth scope. If you also use the Shopper Context API to create or update context, add the sfcc.shopper-context.rw scope to your SLAS API client. See Shopper Context.

Review Shopper Context Best Practices for additional guidance, quota limits, and time-to-live (TTL) considerations for shopper context.

Add Shopper Context Lite to a Request

Add the sfdc_shopper_context header to each personalized Shopper API request that depends on Shopper Context Lite. Set the header value to a minified JSON object.

This example applies shopper context when retrieving a product.

1curl "https://$SHORT_CODE.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/$ORGANIZATION_ID/products/$PRODUCT_ID?siteId=$SITE_ID" \
2    --header "Authorization: Bearer $SLAS_ACCESS_TOKEN" \
3    --header 'sfdc_shopper_context: {"clientIp":"203.0.113.42","sourceCode":"summer2026","customQualifiers":{"deviceType":"mobile","channel":"app"}}'

SHORT_CODE: The short code for your B2C Commerce instance.
ORGANIZATION_ID: The organization ID for your B2C Commerce instance.
PRODUCT_ID: The product ID to retrieve.
SITE_ID: The site ID associated with the SLAS access token.
SLAS_ACCESS_TOKEN: A SLAS shopper access token that authorizes the request.

The request must include valid SLAS authorization and all scopes required by the Shopper API operation.

Shopper Context Lite accepts only these properties in the header value. All properties are optional.

Property	Type	Limits and Behavior
`clientIp`	string	A valid IPv4 address up to 15 characters. Use it for location-derived personalization on the first request.
`sourceCode`	string	An active campaign source code up to 256 characters.
`customQualifiers`	object	Free-form key-value pairs for session-based personalization rules. The object supports a maximum of two properties, and each value supports a maximum of 256 characters.

Shopper Context Lite ignores properties other than clientIp, sourceCode, and customQualifiers. To set other properties, such as assignmentQualifiers, customerGroupIds, couponCodes, effectiveDateTime, or geoLocation, call createShopperContext or updateShopperContext in the Shopper Context API.

Understand Merge and Precedence Behavior

For each request that includes sfdc_shopper_context, B2C Commerce resolves context for the current shopper USID and siteId.

If stored shopper context doesn’t exist, B2C Commerce creates it from the supported header properties.
If stored shopper context exists, B2C Commerce merges the supported header properties into it. Values supplied in the header take precedence over matching stored values. Stored context outside the supplied values remains available.
B2C Commerce stores the combined context only when a supplied property changes.
B2C Commerce applies the combined context to the current request before returning the personalized response.

For example, consider this stored context.

1{
2  "clientIp": "198.51.100.10",
3  "sourceCode": "spring2026",
4  "customQualifiers": {
5    "deviceType": "desktop"
6  },
7  "assignmentQualifiers": {
8    "storeId": "store1"
9  }
10}

The next Shopper API request includes this header value.

1{
2  "sourceCode": "summer2026",
3  "customQualifiers": {
4    "deviceType": "mobile"
5  }
6}

B2C Commerce applies this combined context to the request.

1{
2  "clientIp": "198.51.100.10",
3  "sourceCode": "summer2026",
4  "customQualifiers": {
5    "deviceType": "mobile"
6  },
7  "assignmentQualifiers": {
8    "storeId": "store1"
9  }
10}

The header overrides sourceCode and customQualifiers. The stored clientIp and assignmentQualifiers remain unchanged.

Send the Header on Parallel Requests

Storefronts commonly make several personalized Shopper API requests in parallel, such as requests for product details, prices, inventory, and recommendations. Add the same sfdc_shopper_context header to every parallel request that depends on the context. B2C Commerce compares the supplied values with the stored context and stores an update only when a value changes.

Send consistent header values on concurrent requests. If concurrent requests provide different values for the same shopper context property, request processing order determines the final stored value. Create one immutable context snapshot per page render or navigation, and reuse its serialized header value across all parallel requests.

Important

Combine Shopper Context Lite with the Shopper Context API

Shopper Context Lite is optimized for the small set of values commonly known at page entry. It doesn’t replace create or update operations in the Shopper Context API. A typical integration is:

Build a validated lite-context object from server-trusted request information.
Attach the same serialized object to all relevant Shopper API requests started in parallel for the page.
Call the Shopper Context API when the shopper experience requires properties outside the lite subset.
On later requests, omit the header to use stored context, or continue sending it when those values must change going forward.

Use Shopper Context Lite to apply these properties on the first personalized request:

Client IP address
Source code
Up to two custom qualifiers

Use the Shopper Context API to set or update these properties:

Assignment qualifiers
Coupon codes
Customer group IDs
Effective date and time
Geolocation

Lite header values and full Shopper Context API updates use last-write-wins behavior for overlapping properties. If a later PUT or PATCH request supplies a different value for a property that was set through the header, the last request that B2C Commerce processes determines the value. Coordinate updates so that parallel requests don’t send different values for the same shopper.

Note

Best Practices

Validate Before You Serialize

Don’t forward arbitrary query parameters, cookies, or client-provided JSON directly into the header. Allowlist qualifier keys and validate lengths, formats, and permitted values on the server before you serialize the header.

Don't Send Stale Values

When a supported property is present in the header, it overrides the stored value for that request and becomes part of the merged stored context. Don’t send stale values on every request, because they can overwrite a newer full-context update.

Keep the Request Header Small

The lite payload is bounded, but it contributes to the total request-header size. Use short qualifier keys and only the values required for personalization. Account for authorization, cookies, tracing, and proxy-added headers when you evaluate total header size.

Limitations

Shopper Context Lite supports only clientIp, sourceCode, and customQualifiers. Full personalization still requires the Shopper Context API for properties outside this subset.
Shopper Context Lite doesn’t create promotions, assignments, source code groups, or dynamic customer groups. The header values must match active Business Manager configuration.
Storage lifetimes for shopper context and instance quotas are unchanged.
B2C Commerce scopes the header by the current shopper USID and siteId. It isn’t a global storefront setting.