Skip to content
API Reference
/
/
Create a new 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

Create a new cart

Request

Creates an empty cart for the specified location. The cart is initialized with ACTIVE status and zero totals. Items are added via POST /carts/{cart_id}/items.

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
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
location_idstring(uuid)required

The location this cart is for. Must reference an active location with online_ordering_enabled: true.

customer_idstring or null<= 128 characters

Optional partner-provided customer identifier. When set, the server applies member-specific pricing during price calculation. Can also be set or updated later via PATCH /carts/{cart_id}.

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

Responses

Cart created successfully.

Headers
Locationstring(uri)

URL of the newly created cart resource.

Example: "/carts/c1d2e3f4-a5b6-7890-cdef-1234567890ab"
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"
}

Get cart details

Request

Retrieves the current state of a cart, including all items, computed totals, and status. Returns the cart with server-computed subtotal, total_tax, total_discount, and total.

Security
oauth2
Path
cart_idstring(uuid)required

Unique identifier for the cart.

curl -i -X GET \
  'https://developers.tote.ai/_mock/online-ordering/spec/openapi/carts/{cart_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The requested 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"
}

Abandon a cart

Request

Marks a cart as ABANDONED. This is a soft delete -- the cart data is retained but can no longer be modified or checked out. Only ACTIVE carts can be abandoned.

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
curl -i -X DELETE \
  'https://developers.tote.ai/_mock/online-ordering/spec/openapi/carts/{cart_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Idempotency-Key: d7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23'

Responses

Cart abandoned successfully. No content.

Response
No content

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