StylorDocs

Cart integration

The agent can read the shopper's cart and change it: add an item in a specific size, change a quantity, switch a line to a different size, or remove a line. It never writes to your store itself. The shopper's cart session belongs to your storefront, so the agent tells your client what to change, and your client makes the change and shows the result.

How it works

  1. Before each chat request, your client reads the current cart from the storefront.
  2. It sends that snapshot as cart in the request body.
  3. Receiving a snapshot adds the cart tools to the agent for that turn.
  4. When the agent reads or changes the cart, the stream sends a cart_action event.
  5. For each change, your client updates the storefront cart and shows whether it worked.
  6. Optionally, your client reports the outcome using the intent token from the event.
  7. On the next turn, your client sends a fresh snapshot that reflects the changes.

The cart snapshot

json
{
  "itemCount": 2,
  "total": 168,
  "currency": "USD",
  "items": [
    {
      "key": "43210987654321:8f2c1a9e",
      "title": "Coastal Linen Shirt",
      "variant": "M / Navy",
      "quantity": 1,
      "price": 89,
      "sku": "CLS-NVY-M",
      "image": "https://cdn.example.com/products/coastal-linen-shirt-navy.jpg"
    },
    {
      "key": "43210987654322:1b7e33c0",
      "title": "Everyday Chino",
      "variant": "32 / Stone",
      "quantity": 1,
      "price": 79,
      "sku": "EDC-STN-32",
      "image": "https://cdn.example.com/products/everyday-chino-stone.jpg"
    }
  ]
}
Field Type Description
itemCount integer Total units across all lines.
total number Cart total in major currency units (89.00, not cents).
currency string ISO 4217 code for total and each line's price.
items array The cart lines. Can be empty.
items[].key string Your storefront's stable id for the line. The agent sends it back as lineKey, so use whatever your cart API needs to find the line.
items[].title string The product name as the shopper sees it.
items[].variant string or null The variant label, or null for single-variant products.
items[].quantity integer Units of this line.
items[].price number The line total in major currency units.
items[].sku string or null The SKU of the variant in the cart. Changing a line's size needs this to find the product in your catalogue. Without it, a size change can only match on the exact product name.
items[].image string or null An absolute image URL, used for receipts. It is never sent to the model.

The server does not validate the snapshot. Send the shape shown above: if a field is missing or wrong, the cart tools report errors to the agent instead of doing anything useful.

Enabling the cart tools

Add cart to the chat request:

bash
curl https://stylor.ai/api/v2/agent/chat \
  -H "Authorization: Bearer $STYLOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "Add the navy linen shirt in a medium." }],
    "sessionId": "3b0d4a1e-6f52-4b8a-9d3c-7e2f1a0b9c8d",
    "cart": { "itemCount": 0, "total": 0, "currency": "USD", "items": [] }
  }'
  • Sending a snapshot, even an empty one, enables get_cart, add_to_cart, set_cart_quantity, change_cart_size and remove_from_cart for that turn.
  • Omit cart (or send null) on storefronts where your client cannot change the cart. The agent then has no cart tools at all, so it never offers something it cannot do.
  • Send a fresh snapshot with every request. The agent answers "what's in my cart?" from the snapshot, and uses the line key values in it to target changes.
  • Keep streaming on. With stream: false, cart actions are not returned, so the agent would ask for changes your client never receives.
  • Send sessionId, the session.sessionId from the widget preflight. Without it, add and swap actions carry intent: null and their outcomes cannot be recorded.

The agent changes the cart only when the shopper clearly asks it to. It asks which size before adding anything that comes in more than one.

Cart events

Every cart tool call that has something to show sends one cart_action event. The action field tells you which kind:

action Sent by Meaning Your client must
read get_cart The agent read the snapshot Show it as a receipt. Nothing to change.
add add_to_cart Add a variant Add quantity of sku from the product at url.
quantity set_cart_quantity Set a line's quantity Set line lineKey to quantity (0 removes it).
swap change_cart_size Change a line's size Add sku at the line's quantity, then remove line lineKey.
remove remove_from_cart Remove a line Remove line lineKey.

By the time an event is sent, the server has already checked everything it can. For add and swap that means the item exists in your catalogue, the size is one of its variants, and the variant is in stock. For line actions it means lineKey is in your snapshot. Requests that fail those checks never produce an event: the agent is told why, and usually tells the shopper or asks a follow-up question. No event is sent either when the change would do nothing, such as setting a quantity to its current value or switching to the size the line already has.

The agent is told not to claim a change worked. Your interface is where the shopper sees the confirmation.

read

json
{
  "action": "read",
  "itemCount": 2,
  "total": 168,
  "currency": "USD",
  "items": [
    { "name": "Coastal Linen Shirt", "size": "M / Navy", "quantity": 1, "price": 89, "image": "https://cdn.example.com/products/coastal-linen-shirt-navy.jpg" },
    { "name": "Everyday Chino", "size": "32 / Stone", "quantity": 1, "price": 79, "image": "https://cdn.example.com/products/everyday-chino-stone.jpg" }
  ]
}

This is your own snapshot with the fields renamed for display (title becomes name, variant becomes size). It is already complete, so show it as a finished receipt.

add

json
{
  "action": "add",
  "itemId": "8f2c1a9e-4b7d-4c1e-9a3f-2d6b7e5c1a90",
  "name": "Coastal Linen Shirt",
  "url": "https://shop.example.com/products/coastal-linen-shirt",
  "sku": "CLS-NVY-M",
  "size": "M / Navy",
  "quantity": 1,
  "price": 89,
  "currency": "USD",
  "image": "org_5f3a/ds_9c21/8f2c1a9e-4b7d/0.jpg",
  "intent": "eyJ2IjoxLCJqdGkiOiI3ZjFlIn0.q8vT2rN9..."
}

Find the product on your storefront using url, then add quantity (between 1 and 10) of the variant with sku. price is the variant price, falling back to the product price. image is a storage key, not a URL: build the URL as https://stylor.ai/api/v1/image/<key>. url can be an empty string when the catalogue has no URL for the item.

quantity

json
{
  "action": "quantity",
  "lineKey": "43210987654322:1b7e33c0",
  "name": "Everyday Chino",
  "size": "32 / Stone",
  "from": 1,
  "quantity": 2,
  "price": null,
  "image": "https://cdn.example.com/products/everyday-chino-stone.jpg"
}

Set the line to quantity (between 0 and 50); from is the quantity before the change. price is always null, because the line total changes with the quantity.

swap

json
{
  "action": "swap",
  "lineKey": "43210987654321:8f2c1a9e",
  "name": "Coastal Linen Shirt",
  "fromSize": "M / Navy",
  "size": "L / Navy",
  "sku": "CLS-NVY-L",
  "url": "https://shop.example.com/products/coastal-linen-shirt",
  "quantity": 1,
  "image": "org_5f3a/ds_9c21/8f2c1a9e-4b7d/0.jpg",
  "intent": "eyJ2IjoxLCJqdGkiOiI0YzJhIn0.Zt7mK1pQ..."
}

Add quantity of the new sku first. Remove line lineKey only after the add succeeds. This way a failed add leaves the shopper with the item they already had, and the agent has already told them this is how size changes work. image is the product's storage key, or the line's own image URL when the product has no stored image.

remove

json
{
  "action": "remove",
  "lineKey": "43210987654322:1b7e33c0",
  "name": "Everyday Chino",
  "size": "32 / Stone",
  "quantity": 1,
  "price": 79,
  "image": "https://cdn.example.com/products/everyday-chino-stone.jpg"
}

Remove the line. price is the line total being removed.

Handling cart events in the client

Show the receipt as soon as the event arrives. Do the change in the background, and mark the receipt as done or failed when the storefront responds. When several changes arrive in one turn, apply them in the order they arrived.

javascript
async function handleCartAction(action) {
  const receipt = showReceipt(action, action.action === 'read' ? 'done' : 'pending');
  if (action.action === 'read') return;

  try {
    switch (action.action) {
      case 'add':
        await storefront.addToCart({ url: action.url, sku: action.sku, quantity: action.quantity });
        break;
      case 'quantity':
        await storefront.setQuantity({ lineKey: action.lineKey, quantity: action.quantity });
        break;
      case 'swap':
        await storefront.addToCart({ url: action.url, sku: action.sku, quantity: action.quantity });
        await storefront.removeLine({ lineKey: action.lineKey });
        break;
      case 'remove':
        await storefront.removeLine({ lineKey: action.lineKey });
        break;
    }
    receipt.markDone();
    await reportOutcome(action, null);
  } catch (err) {
    receipt.markFailed(err.message);
    await reportOutcome(action, err.message);
  }
}

Reporting outcomes with intent tokens

add and swap events include intent, a signed, single-use token covering what the server verified: the item, the size and the price. Report whether the change succeeded by sending it to the v1 Track events endpoint, under the event name that matches the action:

action Event name
add cart.item_added
swap cart.size_changed

The product, size and price are read from the token. Your client only reports the outcome:

bash
curl https://stylor.ai/api/v1/events \
  -H "X-Stylor-Session: $STYLOR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "eventId": "2e3f4a5b-6c7d-4e8f-8a9b-0c1d2e3f4a5b",
      "name": "cart.item_added",
      "occurredAt": "2026-09-12T14:05:02.118Z",
      "seq": 9,
      "intent": "eyJ2IjoxLCJqdGkiOiI3ZjFlIn0.q8vT2rN9...",
      "data": { "outcome": "ok", "error": null }
    }]
  }'
  • The events endpoint is authenticated with the session token from the widget preflight, not with your API key.
  • A token is tied to the sessionId you sent with the chat request, is valid for five minutes, and can be used only once.
  • When intent is null (no sessionId was sent), skip the report.
  • quantity, remove and read actions have no intent and nothing to report.

See the v1 Track events reference for the full event schema and rejection reasons.

After the turn

The snapshot you sent is from before the agent's changes. Read the cart again after your client has applied them, and send the new snapshot with the shopper's next message. The agent then works from the real cart, including any change that failed.