Update Basket Contents API

The Basket API provides the ability to add, delete, and modify the contents of a basket. You can add or delete offers, and update the quantity or attributes of an offer that was previously added to a basket. The API works for both known and anonymous users.

You can update the quantity and attributes for root items, child items of parent items, and child items of virtual groups. Some definitions that might be helpful:

  • lineItemKey: A unique key generated for a line item

  • Quantity: The number of items. Includes any root or child item.

  • bundleContextKey: A unique key generated for a bundle

  • cartContextKey: The key for the cart

You use the cartContextKey to keep track of the basket. The cartContextKey is not required if the basket is empty. The cartContextKey is returned as part of the response after a successful basket operation.

Offers may include both products and promotions and use unique offer codes, thereby removing dependency on Salesforce IDs. Offers can be added directly or after configuration.

The API returns the entire bundle structure that is contained in the basket. The list structure complies with pricing, overrides, rules, adjustments, attributes, and so on.

The API uses cartContext to track existing basket contents and appropriate context parameters to price/run rules.

To improve performance, the API returns the contents of the cache if possible. If the data is not cached, the API call is treated as a cache-miss and handled (also resulting in a corresponding cache entry).

The API also permits the user to delete items from an existing basket with the deleteBundleNumber parameter.

The API can be used in any of three ways, depending on the value of the basketAction parameter. The allowable options for basketAction are addWithNoConfig, addAfterConfig, and deleteFromBasket.

If you know the offer code, specify it using the offer parameter, as shown below:

When deleting a bundle from a basket, specify the bundle number in the deleteBundleNumber parameter.

The Fall '20 release includes an Attribute Basket Cache feature. See Attribute Basket Cache Exclusion.

  • Products must have ProductCode populated (no spaces are allowed in ProductCode).

  • Promotions must have Codec populated (no spaces are allowed in Codec).

  • A catalog must be present with products and promotions attached to it as records under the CatalogProductRelationshipc object. The catalog should have CatalogCodec populated (no spaces are allowed in CatalogCode__c).

  • The catalog must be attached to a default price list through the DefaultPriceListc field on the Catalogc object.

  • Price list entries must exist for all the products that are attached to the catalog.

  • Optional: To populate the cache, the following batch jobs may be run:

    • Context combinations

    • Offer details

    • Pricing results

  • Create a custom setting called CacheAPIFields with a value of true. CacheAPIFields is not required for CME 103.1.14 and later versions.

For API parameter names and descriptions, see Digital Commerce REST API.

For detailed API response descriptions, see Digital Commerce REST API

For example, when the basket is empty, to add an item to the basket without configuring:

To add an item to the basket after configuring (by running the previous example and changing the quantity to 2) with basket after previous API call. The productConfig parameter accepts stringified offer details in this example.

To add after configuring (in this case, changing the quantity to 2) with basket after previous API call. The productConfig parameter accepts offer details directly (as a map) in this example.

The list grows from the bottom; that is if you add products A, B, and C in that order, the JSONResult.records list would be C,B,A with respective numbering as 0, 1, and 2. Therefore, list item 0 will always be the most recent addition.

To delete bundle 1 from the basket (assuming the previous API calls were run):

Context parameters can be passed to the API, as in the following examples:

You can add context information if the user is known to the system.

This API supports the isloggedin flag to indicate whether a user is logged in or anonymous. If the isloggedin flag is true, it indicates a logged-in user, and an accountId must be specified in the context parameter of the API call. If the isloggedin flag is false, it indicates that the user is anonymous.

In the returned JSON, the bundleContextKey uniquely identifies a bundle within the basket. Use this key when you need to identify a particular bundle. The lineItemKey parameter uniquely identifies a line item.

Also in the returned JSON, the actions node displays API calls for updating and deleting items.

The following are some examples for logged-in users.

Add a Product to an Empty Basket:

Note that in the following example the basket key is specified in the API:

Add a Child Product to a Basket:

Remove a Product or Child Product from a Basket:

Remove a Child Product from a Basket:

If the API call violates cardinality rules (such as attempting to add or remove more than the maximum or minimum quantity) a message is returned in the messages node (although the API returns no error or error code).

To update the quantity of an item:

To update the quantity of an item:

To update item attributes: