Skip to content
API Reference
/
/
Apply a promo code to a c...

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

Set or update the cart's handoff mode

Request

Sets how the customer wants to receive their order. The handoff mode is stored on the cart and used at checkout. Can be called multiple times to change the mode before checkout (e.g., customer switches from PICKUP to DELIVERY).

The response returns the updated cart with the stored handoff mode.

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
modestringrequired

In-store pickup. Customer arrives at the store and picks up the order at the counter.

Discriminator
Value "PICKUP"
pickup_timestring or null(date-time)

Requested pickup time (ISO 8601). If null, the order is prepared as soon as possible ("ASAP").

curl -i -X PUT \
  'https://developers.tote.ai/_mock/online-ordering/spec/openapi/carts/{cart_id}/handoff' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: d7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23' \
  -d '{
    "mode": "PICKUP",
    "pickup_time": "2019-08-24T14:15:22Z"
  }'

Responses

Handoff mode set successfully. 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": "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"
}

Apply a promo code to a cart

Request

Applies a promo code to the cart. The server validates the code, checks eligibility (expiry, minimum order amount, applicable items), and applies the discount. Returns the updated Cart with the promo in the promo_codes array and the discount reflected in totals.

One promo at a time: Only one promo code can be active on a cart. If a promo code is already applied, the server returns 409 Conflict. Remove the existing code first via DELETE /carts/{cart_id}/promo-codes/{code}.

Case-insensitive: Codes are case-insensitive on input. "summer25" and "SUMMER25" are treated identically. The code is always returned as uppercase.

Discount visibility: The promo discount appears in the PriceCalculation discounts array as a DiscountLineItem with source: PROMO_CODE.

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
codestring<= 30 charactersrequired

The promo code to apply. Case-insensitive.

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

Responses

Promo code applied. Returns the updated cart with the promo in promo_codes and the discount reflected in totals.

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,
  "promo_codes": [
    { … }
  ],
  "subtotal": {
    "amount": 1797,
    "currency": "USD"
  },
  "total_tax": {
    "amount": 127,
    "currency": "USD"
  },
  "total_discount": {
    "amount": 250,
    "currency": "USD"
  },
  "total": {
    "amount": 1674,
    "currency": "USD"
  },
  "created_at": "2026-01-31T10:00:00Z",
  "updated_at": "2026-01-31T10:06:00Z"
}

List promo codes on a cart

Request

Returns the promo codes currently applied to the cart. This information is also included in the Cart response, but this endpoint is useful for checking promo status without fetching the full cart.

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}/promo-codes' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

List of promo codes on the cart.

Bodyapplication/json
dataArray of objects(PromoCode)
Response
application/json
{
  "data": [
    { … }
  ]
}

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