You are here:
Configure Basket Preferences
Configurable basket settings include persistence across shopper sessions, the treatment of duplicate product line items, and the maximum number of product line items per basket. These preferences are site-specific, and a customized storefront doesn’t necessarily evaluate them.
Configure Basket Settings
Configurable basket settings alter:
- The behavior of the dw.order.BasketMgr.getCurrentBasket() and dw.order.BasketMgr.getStoredBasket() methods
- The treatment of duplicate product line items
- The maximum number of product line items per basket.
To set basket behavior preferences for the current site, click App Launcher 
, and then select
Basket Persistence Across Storefront Sessions
Configure site-specific basket settings that control shopper session persistence. These preferences directly influence the behavior of BasketMgr methods, and define the use of the cookies for maintaining basket state across sessions.
Two key identifiers influence basket retrieval:
- dwsid (Session ID): A transient cookie that tracks the current browser session. When dwsid changes (for example, due to session expiration), the system relies on the anonymous cookie for persistence.
- dwanonymous (Anonymous ID Cookie): A persistent cookie used to associate an unregistered (guest) shopper with a unique, saved basket across multiple visits, regardless of dwsid changes. The presence of this cookie determines persistence for guest shoppers.
Global Constraints
The following rules are always in effect, regardless of the settings.
- When an unregistered shopper creates a basket, its association is maintained via the dwanonymous cookie, which stores the shopper's unique ID. This cookie allows the system to retrieve the basket even if the transient session ID (dwsid) changes or expires.
- When a customer creates a basket, and then registers or logs in, that basket remains in the session and ownership of it transfers to the customer.
- When a customer logs out, the current basket is cleared from the session, even if it’s also saved.
- When a basket’s lifetime expires, the basket is no longer accessible and cannot be recreated.
- After seven days of no payment information updates, the system automatically deletes any payment information from a basket.
- A basket that doesn’t belong to a registered customer never persists for longer than 365 days after the last basket interaction by the shopper.
Basket Persistence Settings
The following settings control how long baskets are stored:
- Basket Persistence: Defines the conditions for which the system automatically looks up and restores a saved basket using BasketMgr.getCurrentBasket() when a customer begins a new session. This setting is only relevant if the basket to be returned is still within its configured basket lifetime. This setting is not relevant for SCAPI/OCAPI.
- Basket Lifetimes: Defines how long a saved basket remains available in the system before it becomes unavailable with BasketMgr.getCurrentBasket().
| Basket Persistence | BasketExpirationType IMPEX Preference value (relates to the IMPEX preferences schema and the attribute preference-id=BasketExpirationType) | getCurrentBasket() Behavior | Description |
|---|---|---|---|
| Baskets Not Persistent | Session | Baskets only exist during the storefront session and this method only returns baskets created in the current session. | When a session ends, the basket is not saved. Every session begins with an empty basket. |
| Baskets Persistent for Authenticated Customers Only | Authenticated | An existing basket from a previous session is returned only for registered shoppers who are logged into the new session. | When a registered shopper’s session ends, the current basket is cleared but its contents are saved. If that shopper opens a new session and logs in within the basket lifetime for registered customers, the saved basket is restored. If the shopper started a new basket before logging in, the saved basket is available via BasketMgr.getStoredBasket(). |
| Baskets Persistent for Registered Customers Only | Customer | An existing basket is returned for registered shoppers. If the registered shopper is not logged into the session, and the shopper is only identified by the dwanonymous cookie, personal data is cleared when using this method. | When a registered shopper’s session ends, the current basket is cleared but its contents are saved. If the system recognizes that shopper in a new session within the basket lifetime for registered shoppers, the saved basket is restored. If the shopper started a new basket before being recognized, the saved basket is available via API calls. |
| Baskets Persistent for All Shoppers | Time | For both registered and guest shoppers, an existing basket is returned. However, if the existing basket was created in a previous visit, and the current user is only a guest (identified solely by the dwanonymous cookie), personal data is cleared when using this method. | When any customer’s session ends, the current basket is cleared but its contents are saved. If that customer opens a new session within the basket lifetime for the appropriate customer type, the saved basket contents are restored. |
Basket Retention Settings
To configure the behavior of baskets when user sessions start and end, use the persistence and lifetime settings.
Define different lifetimes for registered and unregistered (guest) customers. The following rules apply to basket lifetimes:
- A basket’s lifetime is measured from the time of its last change.
- The default lifetime for registered customers is 240 minutes (four hours).
- We recommend a lifetime between 20,160 minutes (14 days) and 43,200 minutes (30 days), unless you have a specific use case for a different length. The Maximum Basket Lifetime API quota of 525,600 minutes (365 days) applies to the lifetime for registered customers. For information on API quotas, see the API documentation.
- The maximum lifetime for unregistered customers is the smaller of 43,200 minutes (30 days) or the lifetime for registered customers.
- If you don’t specify a lifetime for unregistered customers, it defaults to the maximum lifetime.
Behavior When Adding a Duplicate Product to a Basket
The Add Product to Basket Behavior setting controls the behavior when a customer tries to add a product that’s identical to one in their basket. Products are compared using the following rules:
- If the preference is Disallow Repeats or Increment Quantity, then products are duplicates if they have the same SKU, product list ID, and inventory list ID. For purposes of this comparison, a null list ID only matches another null list ID. For example, a product that isn’t on an inventory list can only match another product that isn’t on an inventory list.
- If the preference is Allow Repeats, then adding a product doesn’t affect any existing product line items.
- Option products are always added to a new product line item, regardless of the preference setting.
- Product bundles that contain base products are always added to a new product line item, regardless of the preference setting.
- If an attribute changes on a product that’s in the basket, the system does not repeat the duplicate check.
| Add Product to Basket Behavior | Description |
|---|---|
| Disallow Repeats | Ignore the request. |
| Increment Quantity | Add to the quantity of the existing product line item. This setting is the default. |
| Allow Repeats | Add another product line item for the same product. |
Maximum Product Line Items Per Basket
To limit the number of product line items allowed in a basket, enter a value in the Max Number of Product Line Items field. Attempting to add product line items beyond this limit returns an error. The limit considers only the number of lines, not their quantities. The default value is 50.
Temporary Basket
Use the temporary basket API to create a temporary basket in the B2C Commerce system. The temporary basket is enabled with the Shopper Baskets Script API, OCAPI and SCAPI including pricing, promotions, coupons, inventory, shipping methods, order creation, and reopening an order. A temporary basket is populated with all the data required to ready the basket for checkout but differs from a shopper basket in the following ways:
- Basket lifetime is limited to 15 minutes of inactivity.
- A shopper can have up to 10 (default 4) temporary baskets. To configure the number
of temporary baskets, in Business Manager click App Launcher , and then select and set the Temporary Basket per Customer value.
- Available to all shoppers including guests, registered and agent use cases
A temporary basket performs all the necessary calculations to generate accurate totals, line items, promotions, availability, and the like without affecting the regular shopper storefront basket. Use the results of the temporary basket calculations to display purchase information for items added to the temporary basket. And use the same calculations for temporary basket checkout.
A temporary basket is intended for specific use cases. For example:
- A shopper wants to purchase an item that is not added to their normal shopping cart.
- A shopper taps an Apple Pay button on a product display page to buy now without affecting their current storefront basket which contains line items for an unrelated purchase.
- A shopper taps a reorder button on an order history page to repeat a past purchase without affecting their current storefront basket which contains line items for an unrelated purchase.
- A shopper taps an order button on a wish list page to purchase one or more items without affecting their current storefront basket which contains line items for an unrelated purchase.
- A merchant shares a link through social channels that generates a temporary basket for promotional items.
- A customer support agent sends a Buy Now link with pre-set products for a shopper to checkout themselves (no passing of payment details to support).
