Shopper Context

Use the Shopper Context API to personalize shopping experiences:

Access tokens whose scope includes the Shopper Context API are powerful: they can activate specific promotions and be used to see how a storefront would appear in the future. Don't share them with untrusted clients like web browsers or client apps.

It is highly recommended to use Shopper Context calls with a private client and to only make setting Shopper Context calls through a secure backend channel. Users of Shopper Context , should avoid making direct calls through a browser or similar clients where the data can be viewed , to avoid potential misuse.

As part of this, when creating a new public client in SLAS for a tenant, if adding Shopper Context scope is attempted, a warning message is displayed to ensure the user is aware of the pitfalls of doing so.

Let’s look at a shopper’s personalized journey while browsing for jackets in the Northern Trail Outfitters shopping app:

  1. She visits the shopping app and starts as a guest shopper
  2. She’s from Seattle and notices that signing up to receive email promotions gets 15% off her purchase.
  3. After signing up, she logs into the shopping app. The two contexts reveal that:
    • She’s browsing from the city of Seattle.
    • She’s logged into the shopping app.
  4. She takes advantage of the 15% off and makes a purchase!


To use the Shopper Context API, first add the to a SLAS API Client.

Next, provide the shopper's USID and context you would like to set the createShopperContext or updateShopperContext endpoints:

For PRD instances, context is stored for one day for guest shoppers and seven days for registered shoppers. For other instances, a context is stored for one day for both guest and registered shoppers. As a best practice, extend the context periodically by creating a new one.

The number of contexts that can be stored per instance is limited. PRD instances can store one million contexts. Other instances can store five thousand. If the limit is reached, subsequent requests to create a context return an HTTP 400 response.

B2C Instance TypeGuest Shopper TTLRegistered Shopper TTLContext Quota limit
PRD1 day7 days1,000,000
Non-PRD1 day1 day5,000
  • The Shopper Context API doesn't support custom fields and objects.

  • Only a subset of B2C Commerce and OCAPI shopper endpoints are Shopper Context aware:

    • /baskets
    • /baskets/{basket_id}
    • /baskets/{basket_id}/billing_address
    • /baskets/{basket_id}/coupons
    • /baskets/{basket_id}/coupons/{coupon_item_id}
    • /baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id}
    • /baskets/{basket_id}/items
    • /baskets/{basket_id}/items/{item_id}
    • /baskets/{basket_id}/payment_instruments/{payment_instrument_id}
    • /baskets/{basket_id}/payment_methods
    • /baskets/{basket_id}/price_adjustments
    • /baskets/{basket_id}/price_adjustments/{price_adjustment_id}
    • /baskets/{basket_id}/shipments
    • /baskets/{basket_id}/shipments/{shipment_id}
    • /baskets/{basket_id}/shipments/{shipment_id}/shipping_address
    • /baskets/{basket_id}/shipments/{shipment_id}/shipping_method
    • /baskets/{basket_id}/shipments/{shipment_id}/shipping_methods
    • /custom_objects/{object_type}/{key}
    • /customers/{customer_id}/baskets
    • /orders
    • /orders/{order_no}
    • /orders/{order_no}
    • /orders/{order_no}/payment_instruments
    • /orders/{order_no}/payment_instruments/{payment_instrument_id}
    • /orders/{order_no}/payment_methods
    • /product_search
    • /products
    • /search_suggestion