Cart Management Helpers

The cart helper endpoints are stateless utilities that simplify cart operations. They compute the result of adding, removing, or updating items without storing any server-side state.

Optional Helpers

These endpoints are provided for convenience. You can implement your own cart logic if you prefer complete control over the shopping cart experience.

Key Concepts

Stateless Design

The cart helpers are pure functions:

(existingCart, operation) → newCart

• No server-side storage - You manage cart state in your application
• No session required - Each request is independent
• Predictable results - Same input always produces same output

Why Use Cart Helpers?

Benefit	Description
Accurate pricing	Helpers calculate totals using current CatalogSet prices
Modifier validation	Validates required modifiers and selection limits
Consistent structure	Returns properly formatted carts ready for order validation
Reduced complexity	No need to implement cart math and validation yourself

When to Implement Your Own

Consider implementing your own cart logic if you need:

• Offline cart support
• Complex discount/promotion logic
• Custom cart persistence
• Cart merging across sessions

Add Item to Cart

Adds an item to a cart and returns the updated cart with recalculated totals.

POST /helpers/cart/add

Request Body

{
  "cart": null,
  "item": {
    "itemId": "item_burger",
    "quantity": 2,
    "modifierGroups": [
      {
        "modifierGroupId": "mod_size",
        "selectedModifiers": [
          { "itemId": "size_large", "quantity": 1 }
        ]
      }
    ],
    "specialInstructions": "No onions please"
  },
  "catalogSetId": "catalog_123"
}

Field	Description
cart	Existing cart object, or null for new cart
item.itemId	Item to add from the catalog
item.quantity	Number of this item
item.modifierGroups	Selected modifiers
catalogSetId	Required when cart is null

Response

{
  "storeId": "store_456",
  "catalogSetId": "catalog_123",
  "lineItems": [
    {
      "lineItemId": "li_abc123",
      "itemId": "item_burger",
      "name": "Classic Burger",
      "quantity": 2,
      "unitPrice": 14.99,
      "totalPrice": 29.98,
      "modifierGroups": [...],
      "specialInstructions": "No onions please"
    }
  ],
  "totals": {
    "subtotal": 29.98,
    "itemCount": 2
  }
}

Remove Item from Cart

Removes a line item from the cart.

POST /helpers/cart/remove

Request Body

{
  "cart": { ... },
  "lineItemId": "li_abc123"
}

Update Item Quantity

Updates the quantity of an existing line item.

POST /helpers/cart/update

Request Body

{
  "cart": { ... },
  "lineItemId": "li_abc123",
  "quantity": 3
}

Setting quantity: 0 removes the item (same as the remove endpoint).

Error Handling

Error	Description	How to Handle
ITEM_NOT_FOUND	Item ID doesn't exist in CatalogSet	Check itemId against CatalogSet
ITEM_UNAVAILABLE	Item exists but is unavailable	Show unavailable message, remove from cart
INVALID_MODIFIER	Invalid modifier selection	Check modifier against CatalogSet
MODIFIER_REQUIRED	Required modifier not provided	Prompt user to select required modifier
MODIFIER_LIMIT_EXCEEDED	Too many modifiers selected	Check modifier group max/min limits
LINE_ITEM_NOT_FOUND	Line item ID not in cart	Refresh cart state

API Reference

• Cart Add - Add item endpoint
• Cart Remove - Remove item endpoint
• Cart Update - Update quantity endpoint

Related

• CatalogSets - Menu structure for building carts
• Orders - Submitting the cart as an order
• Payments - Payment integration options
• Types - Cart type definitions