Integrate Cart Management and Checkout Initiation in Shopping Muse

Note: This Shopping Muse e-commerce integration is undergoing a gradual rollout, and integration details might change in the coming months.

Cart management and checkout initiation enable Shopping Muse to help shoppers move from product discovery to purchase without leaving the conversational experience. The integration has two parts:

• A one-time setup that connects Shopping Muse to your e-commerce backend and checkout page
• A runtime implementation that sends the shopper’s active cart context in Shopping Muse API calls

Prerequisites

• Shopping Muse is implemented on your site or app
• Your e-commerce backend exposes cart APIs that can retrieve and update a cart by cart ID
• Your e-commerce API supports the request and response structure described in this article, either natively or through middleware
• Your frontend can access the shopper’s active cart ID and include it in each Shopping Muse request

Configure e-commerce actions in Shopping Muse

This is a one-time account setup. Configure your cart management so that Shopping Muse can call your e-commerce backend when the shopper asks to view the cart, add an item, or remove an item.

Cart management

Provide the e-commerce actions API base URL. This is the base URL of the e-commerce API or middleware that supports the required cart actions.

If your e-commerce API requires authentication, provide an API key. If your e-commerce platform does not natively support the required request and response structure, use middleware to map its native cart APIs to the expected contract.

Get cart

Route: GET /carts/{id}

Input: Pass the cart ID as the id path parameter. No request body is required.

Response: Return the full cart object, including id, line_items, currency, and totals. Each line item must include id, item.id, and quantity. Each total must include type and amount.

Update cart

Route: PUT /carts/{id}

Input: Pass the cart ID as the id path parameter. The request body must include line_items, with each line item containing item.id and quantity.

Response: Return the same full cart object returned by GET /carts/{id}, including id, line_items, currency, and totals.

Initiate checkout

Provide the checkout page URL that Shopping Muse uses when the shopper asks to check out. The checkout page must resolve the shopper’s active cart using the cart context passed to Shopping Muse at runtime.

Send cart context in Shopping Muse API calls

At runtime, Shopping Muse needs the shopper’s active cart ID to perform cart management and checkout actions on the correct cart.

If you use the out-of-the-box chat template, the template passes the cart ID automatically. If you use a custom implementation, include the shopper’s active cart ID in every Shopping Muse API request when the shopper has an active cart.

The cart ID must represent the active cart in your e-commerce backend. If the cart ID changes during the session, send the updated value in the next Shopping Muse request. Without the cart ID, Shopping Muse cannot retrieve or update the cart or initiate checkout.

Example: Include a cart ID in a Shopping Muse API request

...
cartId: "cart_12345",
query: { text: "Add the blue jacket to my cart" }
...

Validate the integration

Before launch, validate the complete shopper flow in a staging environment:

1. Start a Shopping Muse conversation
2. Ask to view the cart
3. Add a recommended product
4. Remove an item
5. Continue to checkout

Confirm that each action updates the correct cart, returns the latest cart state, and sends the shopper to the expected checkout page.