Skip to content
API Reference
/
/
Add an item to the cart

Tote Online Ordering API (1.0.0)

REST API for 3rd party developers building online ordering integrations with Tote POS convenience stores and fuel stations.

Overview

The Tote Online Ordering API enables partners to:

  • Authenticate via OAuth 2.0 client credentials
  • Browse store locations and business hours
  • Retrieve full menus with nested modifier groups
  • Create and manage shopping carts
  • Submit orders with split payment support
  • Track order fulfillment status
  • Subscribe to webhook events for real-time updates
  • Check item availability and inventory

Base URL

The server URLs below are placeholders. Your actual API base URL, client ID, and client secret are provided during partner onboarding. Contact developer@totepos.com to get started.

Path parameters use snake_case. JSON response fields use snake_case. Schema names use PascalCase. Enum values use SCREAMING_SNAKE_CASE.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
Tote Developer Support
developer@totepos.com
Languages
Servers
Mock server
https://developers.tote.ai/_mock/online-ordering/spec/openapi
Production (placeholder -- use your assigned base URL)
https://api.tote.ai/v1/online-ordering
Sandbox (placeholder -- use your assigned base URL)
https://sandbox.api.tote.ai/v1/online-ordering

Authentication

OAuth 2.0 client credentials token management.

Operations

Locations

Store locations, hours, and capabilities.

Operations

Carts

Shopping cart creation, item management, pricing, and checkout.

Operations

Update cart properties

Request

Partially updates a cart's properties. Currently supports updating the customer_id field. The cart must be in ACTIVE status.

Customer identity: Setting customer_id enables the server to apply member-specific pricing on the next /calculate call. Setting customer_id to null reverts to anonymous pricing. After changing customer_id, re-calculate prices -- previous pricing may be stale.

Idempotency: This endpoint supports idempotent requests. Include an Idempotency-Key header (UUID v4) to safely retry requests.

Security
oauth2
Path
cart_idstring(uuid)required

Unique identifier for the cart.

Headers
Idempotency-Keystring(uuid)<= 40 charactersrequired

A unique key (UUID v4) to ensure idempotent request processing. Required on all POST, PUT, and DELETE requests.

If a request is retried with the same key within 24 hours, the server returns the cached success response without re-processing. Error responses are NOT cached -- retrying after an error with the same key will re-execute the request.

Generate a new UUID v4 for each unique operation. Reuse the same key only when retrying a failed or timed-out request.

Example: d7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23
Bodyapplication/jsonrequired
customer_idstring or null<= 128 characters

Partner-provided customer identifier. Set to null to remove customer identity and revert to anonymous pricing.

Example: "CUST-12345"
curl -i -X PATCH \
  'https://developers.tote.ai/_mock/online-ordering/spec/openapi/carts/{cart_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: d7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23' \
  -d '{
    "customer_id": "CUST-12345"
  }'

Responses

Cart updated. Returns the full updated cart.

Bodyapplication/json
idstring(uuid)required

Unique identifier for the cart.

location_idstring(uuid)required

The location this cart belongs to.

customer_idstring or null<= 128 characters

Partner-provided customer identifier. When set, the server applies member-specific pricing during price calculation. Can be set at creation (POST /carts) or updated later (PATCH /carts/{cart_id}). Set to null to revert to anonymous pricing.

After changing customer_id, re-calculate prices -- previous pricing may be stale.

Example: "CUST-12345"
statusstringrequired

Current cart status. ACTIVE carts accept modifications. CHECKED_OUT carts have been converted to orders via checkout. ABANDONED carts were explicitly deleted by the client.

Enum"ACTIVE""CHECKED_OUT""ABANDONED"
itemsArray of objects(CartItem)required

Line items in the cart.

items[].​idstring(uuid)required

Unique identifier for this cart item (generated server-side).

items[].​menu_item_idstring(uuid)required

Reference to the menu item (from GET /locations/{location_id}/menu).

items[].​namestringrequired

Display name of the menu item (copied from menu at add time).

items[].​quantityinteger>= 1required

Number of this item in the cart.

items[].​base_priceobject(Money)required

Base price per unit (from the menu item).

items[].​base_price.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
items[].​base_price.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
items[].​modifier_totalobject(Money)required

Total price of all selected modifiers per unit.

items[].​modifier_total.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
items[].​modifier_total.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
items[].​item_totalobject(Money)required

Total for this line item: (base_price + modifier_total) * quantity.

items[].​item_total.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
items[].​item_total.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
items[].​modifier_selectionsArray of objects(ModifierSelection)required

Modifiers selected for this item.

items[].​modifier_selections[].​modifier_group_idstring(uuid)required

ID of the modifier group this selection belongs to.

items[].​modifier_selections[].​modifier_idstring(uuid)required

ID of the selected modifier within the group.

items[].​modifier_selections[].​quantityinteger>= 1

Quantity of this modifier. Relevant for modifier groups with allows_duplicates: true (e.g., "Extra Cheese x2").

Default 1
items[].​modifier_selections[].​nested_selectionsArray of objects(ModifierSelection)

Selections for nested modifier groups. For example, selecting "Steak" as a protein, then choosing "Medium" from the steak preparation sub-group. Supports up to 3 nesting levels, matching the menu's modifier group depth.

items[].​special_instructionsstring or null<= 200 characters

Customer's special instructions for this item (e.g., "no onions", "extra ice"). Null if none were provided. Max 200 characters.

items[].​age_verification_requiredboolean

True if this specific item requires age verification. Copied from the menu item's age_verification_required flag.

Default false
items[].​minimum_ageinteger or null

Minimum age required to purchase this item (e.g., 21 for tobacco/alcohol). Null if age verification is not required.

handoff_modeHandoffMode (any) or null

The handoff mode set for this cart, or null if not yet selected. Set via PUT /carts/{cart_id}/handoff. Required before checkout.

One of:

The handoff mode set for this cart, or null if not yet selected. Set via PUT /carts/{cart_id}/handoff. Required before checkout.

age_verification_requiredboolean

True if any item in the cart requires age verification (e.g., tobacco, alcohol). This is an informational flag -- age-restricted items are NOT blocked from the cart. The consumer will be verified offline at pickup or delivery.

Default false
promo_codesArray of objects(PromoCode)

Promo codes currently applied to this cart. Only one promo code can be active at a time. Applied via POST /carts/{cart_id}/promo-codes.

subtotalobject(Money)required

Sum of all item totals before tax and discounts.

subtotal.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
subtotal.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
total_taxobject(Money)required

Total tax amount for the cart.

total_tax.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
total_tax.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
total_discountobject(Money)

Total of cart-level discounts applied to the cart. Item-level discounts are reflected in each item's total.

feesArray of objects(FeeLineItem)

Fees currently applied to this cart. Recalculated on each cart modification. Call POST /carts/{cart_id}/calculate for the authoritative fee breakdown.

total_feesobject(Money)

Sum of all fee amounts currently applied to the cart.

totalobject(Money)required

Grand total: subtotal + total_tax + total_fees - total_discount.

total.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
total.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
created_atstring(date-time)required

Timestamp when the cart was created.

updated_atstring(date-time)required

Timestamp when the cart was last modified.

Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
  "customer_id": "CUST-12345",
  "status": "ACTIVE",
  "items": [
    { … }
  ],
  "handoff_mode": {
    "mode": "PICKUP",
    "pickup_time": "2019-08-24T14:15:22Z"
  },
  "age_verification_required": false,
  "promo_codes": [
    { … }
  ],
  "subtotal": {
    "amount": 1299,
    "currency": "USD"
  },
  "total_tax": {
    "amount": 1299,
    "currency": "USD"
  },
  "total_discount": {
    "amount": 1299,
    "currency": "USD"
  },
  "fees": [
    { … }
  ],
  "total_fees": {
    "amount": 1299,
    "currency": "USD"
  },
  "total": {
    "amount": 1299,
    "currency": "USD"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Add an item to the cart

Request

Adds a menu item with optional modifier selections to the cart. The server validates that the menu item exists, is available, and that modifier selections satisfy the min_selections/max_selections constraints of each modifier group.

Age-restricted items can be added freely. The cart's age_verification_required flag will be set to true, and the consumer will be informed that verification is required at pickup or delivery.

The response includes the updated cart with recalculated totals.

Idempotency: This endpoint supports idempotent requests. Include an Idempotency-Key header (UUID v4) to safely retry requests. Successful responses are cached for 24 hours; error responses are not cached.

Security
oauth2
Path
cart_idstring(uuid)required

Unique identifier for the cart.

Headers
Idempotency-Keystring(uuid)<= 40 charactersrequired

A unique key (UUID v4) to ensure idempotent request processing. Required on all POST, PUT, and DELETE requests.

If a request is retried with the same key within 24 hours, the server returns the cached success response without re-processing. Error responses are NOT cached -- retrying after an error with the same key will re-execute the request.

Generate a new UUID v4 for each unique operation. Reuse the same key only when retrying a failed or timed-out request.

Example: d7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23
Bodyapplication/jsonrequired
menu_item_idstring(uuid)required

ID of the menu item to add (from GET /locations/{location_id}/menu). The server validates that this item exists and is available.

quantityinteger>= 1required

Number of this item to add.

modifier_selectionsArray of objects(ModifierSelection)

Selected modifiers for this item. Must satisfy the min_selections and max_selections constraints of each modifier group defined in the menu. If a modifier group has min_selections > 0 and no selection is provided for it, the server returns a 422 error.

special_instructionsstring or null<= 200 characters

Free-text instructions for this item (e.g., "no onions", "extra ice"). Max 200 characters. Null or omitted if no special instructions.

curl -i -X POST \
  'https://developers.tote.ai/_mock/online-ordering/spec/openapi/carts/{cart_id}/items' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: d7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23' \
  -d '{
    "menu_item_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "quantity": 1,
    "modifier_selections": [
      {
        "modifier_group_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "modifier_id": "a2b3c4d5-e6f7-8901-bcde-f12345678901",
        "quantity": 1,
        "nested_selections": []
      },
      {
        "modifier_group_id": "b3c4d5e6-f7a8-9012-cdef-123456789012",
        "modifier_id": "c4d5e6f7-a8b9-0123-def0-234567890123",
        "quantity": 1,
        "nested_selections": [
          {
            "modifier_group_id": "d5e6f7a8-b9c0-1234-ef01-345678901234",
            "modifier_id": "e6f7a8b9-c0d1-2345-f012-456789012345",
            "quantity": 1,
            "nested_selections": []
          }
        ]
      }
    ]
  }'

Responses

Item added to the cart. Returns the updated cart.

Bodyapplication/json
idstring(uuid)required

Unique identifier for the cart.

location_idstring(uuid)required

The location this cart belongs to.

customer_idstring or null<= 128 characters

Partner-provided customer identifier. When set, the server applies member-specific pricing during price calculation. Can be set at creation (POST /carts) or updated later (PATCH /carts/{cart_id}). Set to null to revert to anonymous pricing.

After changing customer_id, re-calculate prices -- previous pricing may be stale.

Example: "CUST-12345"
statusstringrequired

Current cart status. ACTIVE carts accept modifications. CHECKED_OUT carts have been converted to orders via checkout. ABANDONED carts were explicitly deleted by the client.

Enum"ACTIVE""CHECKED_OUT""ABANDONED"
itemsArray of objects(CartItem)required

Line items in the cart.

items[].​idstring(uuid)required

Unique identifier for this cart item (generated server-side).

items[].​menu_item_idstring(uuid)required

Reference to the menu item (from GET /locations/{location_id}/menu).

items[].​namestringrequired

Display name of the menu item (copied from menu at add time).

items[].​quantityinteger>= 1required

Number of this item in the cart.

items[].​base_priceobject(Money)required

Base price per unit (from the menu item).

items[].​base_price.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
items[].​base_price.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
items[].​modifier_totalobject(Money)required

Total price of all selected modifiers per unit.

items[].​modifier_total.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
items[].​modifier_total.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
items[].​item_totalobject(Money)required

Total for this line item: (base_price + modifier_total) * quantity.

items[].​item_total.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
items[].​item_total.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
items[].​modifier_selectionsArray of objects(ModifierSelection)required

Modifiers selected for this item.

items[].​modifier_selections[].​modifier_group_idstring(uuid)required

ID of the modifier group this selection belongs to.

items[].​modifier_selections[].​modifier_idstring(uuid)required

ID of the selected modifier within the group.

items[].​modifier_selections[].​quantityinteger>= 1

Quantity of this modifier. Relevant for modifier groups with allows_duplicates: true (e.g., "Extra Cheese x2").

Default 1
items[].​modifier_selections[].​nested_selectionsArray of objects(ModifierSelection)

Selections for nested modifier groups. For example, selecting "Steak" as a protein, then choosing "Medium" from the steak preparation sub-group. Supports up to 3 nesting levels, matching the menu's modifier group depth.

items[].​special_instructionsstring or null<= 200 characters

Customer's special instructions for this item (e.g., "no onions", "extra ice"). Null if none were provided. Max 200 characters.

items[].​age_verification_requiredboolean

True if this specific item requires age verification. Copied from the menu item's age_verification_required flag.

Default false
items[].​minimum_ageinteger or null

Minimum age required to purchase this item (e.g., 21 for tobacco/alcohol). Null if age verification is not required.

handoff_modeHandoffMode (any) or null

The handoff mode set for this cart, or null if not yet selected. Set via PUT /carts/{cart_id}/handoff. Required before checkout.

One of:

The handoff mode set for this cart, or null if not yet selected. Set via PUT /carts/{cart_id}/handoff. Required before checkout.

age_verification_requiredboolean

True if any item in the cart requires age verification (e.g., tobacco, alcohol). This is an informational flag -- age-restricted items are NOT blocked from the cart. The consumer will be verified offline at pickup or delivery.

Default false
promo_codesArray of objects(PromoCode)

Promo codes currently applied to this cart. Only one promo code can be active at a time. Applied via POST /carts/{cart_id}/promo-codes.

subtotalobject(Money)required

Sum of all item totals before tax and discounts.

subtotal.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
subtotal.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
total_taxobject(Money)required

Total tax amount for the cart.

total_tax.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
total_tax.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
total_discountobject(Money)

Total of cart-level discounts applied to the cart. Item-level discounts are reflected in each item's total.

feesArray of objects(FeeLineItem)

Fees currently applied to this cart. Recalculated on each cart modification. Call POST /carts/{cart_id}/calculate for the authoritative fee breakdown.

total_feesobject(Money)

Sum of all fee amounts currently applied to the cart.

totalobject(Money)required

Grand total: subtotal + total_tax + total_fees - total_discount.

total.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
total.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
created_atstring(date-time)required

Timestamp when the cart was created.

updated_atstring(date-time)required

Timestamp when the cart was last modified.

Response
application/json
{
  "id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
  "location_id": "b5a7c8d9-e0f1-4a2b-8c3d-4e5f6a7b8c9d",
  "status": "ACTIVE",
  "items": [
    { … },
    { … }
  ],
  "age_verification_required": false,
  "subtotal": {
    "amount": 1797,
    "currency": "USD"
  },
  "total_tax": {
    "amount": 148,
    "currency": "USD"
  },
  "total_discount": {
    "amount": 0,
    "currency": "USD"
  },
  "total": {
    "amount": 1945,
    "currency": "USD"
  },
  "created_at": "2026-01-31T10:00:00Z",
  "updated_at": "2026-01-31T10:05:30Z"
}

Update a cart item

Request

Updates the quantity and/or modifier selections of an existing cart item. The full CartItemRequest must be provided (this is a full replacement, not a patch). The server re-validates modifier constraints against the current menu.

The response includes the updated cart with recalculated totals.

Idempotency: This endpoint supports idempotent requests. Include an Idempotency-Key header (UUID v4) to safely retry requests. Successful responses are cached for 24 hours; error responses are not cached.

Security
oauth2
Path
cart_idstring(uuid)required

Unique identifier for the cart.

item_idstring(uuid)required

Unique identifier for the cart item.

Headers
Idempotency-Keystring(uuid)<= 40 charactersrequired

A unique key (UUID v4) to ensure idempotent request processing. Required on all POST, PUT, and DELETE requests.

If a request is retried with the same key within 24 hours, the server returns the cached success response without re-processing. Error responses are NOT cached -- retrying after an error with the same key will re-execute the request.

Generate a new UUID v4 for each unique operation. Reuse the same key only when retrying a failed or timed-out request.

Example: d7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23
Bodyapplication/jsonrequired
menu_item_idstring(uuid)required

ID of the menu item to add (from GET /locations/{location_id}/menu). The server validates that this item exists and is available.

quantityinteger>= 1required

Number of this item to add.

modifier_selectionsArray of objects(ModifierSelection)

Selected modifiers for this item. Must satisfy the min_selections and max_selections constraints of each modifier group defined in the menu. If a modifier group has min_selections > 0 and no selection is provided for it, the server returns a 422 error.

special_instructionsstring or null<= 200 characters

Free-text instructions for this item (e.g., "no onions", "extra ice"). Max 200 characters. Null or omitted if no special instructions.

curl -i -X PUT \
  'https://developers.tote.ai/_mock/online-ordering/spec/openapi/carts/{cart_id}/items/{item_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: d7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23' \
  -d '{
    "menu_item_id": "1eaad7ed-b0ad-40c9-9def-254fcdb506fd",
    "quantity": 1,
    "modifier_selections": [
      {
        "modifier_group_id": "1566848b-12d7-4b42-af90-44087c647a83",
        "modifier_id": "fee78d56-6d48-42b7-9517-8ba0bf9ae013",
        "quantity": 1,
        "nested_selections": [
          {}
        ]
      }
    ],
    "special_instructions": "string"
  }'

Responses

Cart item updated. Returns the updated cart.

Bodyapplication/json
idstring(uuid)required

Unique identifier for the cart.

location_idstring(uuid)required

The location this cart belongs to.

customer_idstring or null<= 128 characters

Partner-provided customer identifier. When set, the server applies member-specific pricing during price calculation. Can be set at creation (POST /carts) or updated later (PATCH /carts/{cart_id}). Set to null to revert to anonymous pricing.

After changing customer_id, re-calculate prices -- previous pricing may be stale.

Example: "CUST-12345"
statusstringrequired

Current cart status. ACTIVE carts accept modifications. CHECKED_OUT carts have been converted to orders via checkout. ABANDONED carts were explicitly deleted by the client.

Enum"ACTIVE""CHECKED_OUT""ABANDONED"
itemsArray of objects(CartItem)required

Line items in the cart.

items[].​idstring(uuid)required

Unique identifier for this cart item (generated server-side).

items[].​menu_item_idstring(uuid)required

Reference to the menu item (from GET /locations/{location_id}/menu).

items[].​namestringrequired

Display name of the menu item (copied from menu at add time).

items[].​quantityinteger>= 1required

Number of this item in the cart.

items[].​base_priceobject(Money)required

Base price per unit (from the menu item).

items[].​base_price.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
items[].​base_price.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
items[].​modifier_totalobject(Money)required

Total price of all selected modifiers per unit.

items[].​modifier_total.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
items[].​modifier_total.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
items[].​item_totalobject(Money)required

Total for this line item: (base_price + modifier_total) * quantity.

items[].​item_total.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
items[].​item_total.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
items[].​modifier_selectionsArray of objects(ModifierSelection)required

Modifiers selected for this item.

items[].​modifier_selections[].​modifier_group_idstring(uuid)required

ID of the modifier group this selection belongs to.

items[].​modifier_selections[].​modifier_idstring(uuid)required

ID of the selected modifier within the group.

items[].​modifier_selections[].​quantityinteger>= 1

Quantity of this modifier. Relevant for modifier groups with allows_duplicates: true (e.g., "Extra Cheese x2").

Default 1
items[].​modifier_selections[].​nested_selectionsArray of objects(ModifierSelection)

Selections for nested modifier groups. For example, selecting "Steak" as a protein, then choosing "Medium" from the steak preparation sub-group. Supports up to 3 nesting levels, matching the menu's modifier group depth.

items[].​special_instructionsstring or null<= 200 characters

Customer's special instructions for this item (e.g., "no onions", "extra ice"). Null if none were provided. Max 200 characters.

items[].​age_verification_requiredboolean

True if this specific item requires age verification. Copied from the menu item's age_verification_required flag.

Default false
items[].​minimum_ageinteger or null

Minimum age required to purchase this item (e.g., 21 for tobacco/alcohol). Null if age verification is not required.

handoff_modeHandoffMode (any) or null

The handoff mode set for this cart, or null if not yet selected. Set via PUT /carts/{cart_id}/handoff. Required before checkout.

One of:

The handoff mode set for this cart, or null if not yet selected. Set via PUT /carts/{cart_id}/handoff. Required before checkout.

age_verification_requiredboolean

True if any item in the cart requires age verification (e.g., tobacco, alcohol). This is an informational flag -- age-restricted items are NOT blocked from the cart. The consumer will be verified offline at pickup or delivery.

Default false
promo_codesArray of objects(PromoCode)

Promo codes currently applied to this cart. Only one promo code can be active at a time. Applied via POST /carts/{cart_id}/promo-codes.

subtotalobject(Money)required

Sum of all item totals before tax and discounts.

subtotal.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
subtotal.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
total_taxobject(Money)required

Total tax amount for the cart.

total_tax.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
total_tax.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
total_discountobject(Money)

Total of cart-level discounts applied to the cart. Item-level discounts are reflected in each item's total.

feesArray of objects(FeeLineItem)

Fees currently applied to this cart. Recalculated on each cart modification. Call POST /carts/{cart_id}/calculate for the authoritative fee breakdown.

total_feesobject(Money)

Sum of all fee amounts currently applied to the cart.

totalobject(Money)required

Grand total: subtotal + total_tax + total_fees - total_discount.

total.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
total.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
created_atstring(date-time)required

Timestamp when the cart was created.

updated_atstring(date-time)required

Timestamp when the cart was last modified.

Response
application/json
{
  "id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
  "location_id": "b5a7c8d9-e0f1-4a2b-8c3d-4e5f6a7b8c9d",
  "status": "ACTIVE",
  "items": [
    { … },
    { … }
  ],
  "age_verification_required": false,
  "subtotal": {
    "amount": 1797,
    "currency": "USD"
  },
  "total_tax": {
    "amount": 148,
    "currency": "USD"
  },
  "total_discount": {
    "amount": 0,
    "currency": "USD"
  },
  "total": {
    "amount": 1945,
    "currency": "USD"
  },
  "created_at": "2026-01-31T10:00:00Z",
  "updated_at": "2026-01-31T10:05:30Z"
}

Orders

Order retrieval, fulfillment tracking, and cancellation.

Operations

Payments

Payment submission, split payments, and refunds.

Operations

Webhook Subscriptions

Webhook subscription management and event delivery.

Operations

Inventory

Item availability and stock status.

Operations

Events

Webhook event payloads delivered to your subscription URLs.

Webhooks