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

Integration overview

Storefront or backend
        |
        | Shopping Muse request + cart ID
        v
   Shopping Muse
        |
        | GET /carts/{id}
        | PUT /carts/{id}
        v
Merchant cart API
        |
        | Optional middleware
        v
Commerce platform

If your commerce platform doesn't support the required API contract directly, use middleware to translate between the Shopping Muse contract and the platform's native cart APIs.

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.
• The shopper's active cart ID is available wherever the Shopping Muse request is constructed:
  • For a client-side implementation, the cart ID must be available in the storefront/browser.
  • For an API implementation, the cart ID must be available to the backend making the Shopping Muse request.
• Product IDs used by your commerce platform can be mapped to the SKU used in your Dynamic Yield product feed.

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, update a quantity, 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. Shopping Muse sends the configured key in the x-api-key request header.

Your API must also expose a health endpoint that Dynamic Yield uses to verify the connection.

Health check

Route: GET /health

Input: No request body is required.

Response: Return HTTP 200 when the service is available.

The health endpoint is used by Dynamic Yield to verify connectivity to the configured e-commerce actions API.

Get cart

Route: GET /carts/{id}

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

Response: Return the current cart. The response must include cart_id, line_items, and total_estimate. Each line item must include cart_id, item.id, quantity, and price.

Example:

{
  "cart_id": "cart_12345",
  "line_items": [
    {
      "id": "line_123",
      "item": {
        "id": "SKU_123"
      },
      "quantity": 1,
      "price": {
        "amount": "129.00",
        "currency": "USD"
      }
    }
  ],
  "total_estimate": {
    "amount": "129.00",
    "currency": "USD"
  }
}

Additional UCP cart fields can be returned as supported by your commerce implementation.

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.

Example:

{
  "line_items": [
    {
      "item": {
        "id": "SKU_123"
      },
      "quantity": 1
    },
    {
      "item": {
        "id": "SKU_456"
      },
      "quantity": 1
    }
  ]
}

Process the update according to the UCP cart update semantics. The commerce platform should remain the source of truth for the resulting cart state, including inventory or other merchant-side adjustments.

Response: Return the same response structure as GET /carts/{id} .

Example:

{
  "cart_id": "cart_12345",
  "line_items": [
    {
      "id": "line_123",
      "item": {
        "id": "SKU_123"
      },
      "quantity": 1,
      "price": {
        "amount": "129.00",
        "currency": "USD"
      }
    },
    {
      "id": "line_456",
      "item": {
        "id": "SKU_456"
      },
      "quantity": 1,
      "price": {
        "amount": "49.00",
        "currency": "USD"
      }
    }
  ],
  "total_estimate": {
    "amount": "178.00",
    "currency": "USD"
  }
}

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.

The cart ID is passed to Shopping Muse as commerce.cart_id.

Out-of-the-box Shopping Muse template

If you use the out-of-the-box Shopping Muse template, store the active cart ID in the browser's sessionStorage under the key cart_id.

For example:

sessionStorage.setItem("cart_id", "cart_12345");

The template reads this value and includes it as commerce.cart_id in requests to Shopping Muse.

Update the stored value if the active cart changes during the session.

Shopping Muse API implementation

If you call the Shopping Muse API directly, include the active cart ID in the commerce object as part of the Shopping Muse API request:

sessionStorage.setItem("cart_id", "cart_12345");

The rest of the request follows the standard Shopping Muse API request schema.

Without commerce.cart_id, Shopping Muse can't retrieve or update the cart or initiate checkout.

Operational and security recommendations

• Expose the e-commerce actions API over HTTPS.
• Keep API keys and commerce-platform credentials server-side.
• Validate the x-api-key header on cart API requests.
• Keep GET /health available so Dynamic Yield can verify the connection.
• Treat cart IDs as opaque values and preserve the complete ID when passing it between systems.
• If a cart ID contains sensitive information, such as a platform-specific key, redact it from logs.
• Return the actual cart state produced by your commerce platform after an update rather than echoing the requested cart.

Validate the integration

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

1. Set the commerce integration in the Shopping Muse App and validate it.
2. Start a Shopping Muse conversation with an active cart.
3. Ask to view the cart.
4. Add a recommended product.
5. Update the quantity of an item.
6. Remove an item.
7. Continue to checkout.

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

When validating an update, also confirm that the item.id returned for an added or updated product matches the SKU Shopping Muse sent in the update request.