Cart Composition for Agents - Droplinked Developers

start_checkout was the original “find ⇨ buy” path: an agent calls it once with a SKU, gets back a hosted Droplinked checkout URL, and hands the buyer off to pay. That works for single-SKU intent (“buy this thing”) but not for multi-turn agentic composition, where the agent (or buyer) wants to try a cart configuration before paying. The four cart-mutation tools close that loop:

Tool	What it does
`cart.addLine`	Add another SKU to an existing cart
`cart.updateLineQuantity`	Change the quantity of a SKU already in the cart
`cart.removeLine`	Remove a SKU from the cart
`cart.applyDiscount`	Apply a merchant-issued discount / coupon code

All four expect the encrypted cartId returned by start_checkout — pass it back verbatim; it’s already obfuscated by the backend’s DecryptCartIdPipe.

Canonical multi-line composition flow

search_products({ query: "blue sneaker size 10" })       → [skuA, skuB, …]
start_checkout({ shopId, skuId: skuA, quantity: 1, … })  → { cartId, checkoutUrl }
cart.addLine({ cartId, skuId: skuB, quantity: 2 })        → updated cart
cart.updateLineQuantity({ cartId, skuId: skuA, quantity: 3 })
                                                              → bumped cart total
cart.applyDiscount({ cartId, discountCode: "WELCOME10" }) → discount applied
Buyer (or agent) navigates to `checkoutUrl` and pays

Each step returns the updated cart envelope so the agent can show the running subtotal, line list, and discount before commit. There is no separate “preview” call — every mutation is the preview.

Tool reference

`cart.addLine`

{
  "cartId": "ENC:...",
  "skuId":  "65ab12cd34ef567890123456",
  "quantity": 2
}

Idempotent on (cartId, skuId): calling twice with the same SKU bumps the quantity on the existing line rather than creating a duplicate. Backs: POST /v2/carts/:cartId/products

`cart.updateLineQuantity`

{
  "cartId":   "ENC:...",
  "skuId":    "65ab12cd34ef567890123456",
  "quantity": 5
}

Sets the line to the specified quantity. Passing quantity: 0 removes the line — same effect as calling cart.removeLine but in a single call, which is convenient when the agent is decrementing. Backs: PATCH /v2/carts/:cartId/products/:skuId

`cart.removeLine`

{
  "cartId": "ENC:...",
  "skuId":  "65ab12cd34ef567890123456"
}

Removes the line entirely. The returned cart shows the updated lines + total. Removing the last line leaves the cart empty but still usable — the buyer can continue browsing and the agent can add new lines. Backs: DELETE /v2/carts/:cartId/products/:skuId

`cart.applyDiscount`

{
  "cartId":       "ENC:...",
  "discountCode": "SAVE20"
}

Validates the discount code at the merchant level, computes the discount, and returns the updated cart with the discount amount + label resolved. The code is case-insensitive on the backend but is preserved on the MCP surface so agents can run idempotency checks against the exact value they sent. An invalid or expired code surfaces as a structured error envelope. Backs: POST /v2/carts/:cartId/coupon

Error envelope

All four tools follow the same envelope shape so agents can branch on JSON instead of catching exceptions:

// Happy path
{ "status": "ok", "cartId": "ENC:...", "...": "..." }

// Failure (backend error, validation error, network error)
{ "status": "error", "reason": "<reason_enum>", "message": "…human-readable…" }

The structured reason enum lets agents branch programmatically (e.g. reason: "INVALID_COUPON" vs reason: "BACKEND_5XX").

When NOT to use the cart-mutation tools

Agent only knows the buyer wants one SKU: use start_checkout alone. The mutation tools are pure overhead for single-SKU intent.
Agent is composing for an unauthenticated buyer: there is no “guest cart” — the cart belongs to the email passed to start_checkout. Mutations apply to that cart.
Agent wants to express discount programmatically: the only discount surface is the discount code. There is no cart.applyPercentageOff or similar — merchants own their promo logic via discount codes.

Inventory MCP — full tool inventory
MCP Server — installation and environment reference
Storefront MCP discovery — the search_products / get_product family that precedes start_checkout
ACP feed — the bulk-discovery feed agents can crawl before cart-composing

​Canonical multi-line composition flow

​Tool reference

​cart.addLine

​cart.updateLineQuantity

​cart.removeLine

​cart.applyDiscount

​Error envelope

​When NOT to use the cart-mutation tools

​Related