Skip to content
API Reference
/
/
Validate a promo code wit...

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

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": [
    { … }
  ]
}

Validate a promo code without applying

Request

Checks if a promo code is valid for this cart without applying it. Returns a discount preview (estimated amount, description, applicable items) for valid codes, or a rejection reason and message for invalid codes.

Use this endpoint to show the customer what discount they would receive before they commit to applying the code.

Note: The discount preview is an estimate. The actual discount is computed when the code is applied via POST /carts/{cart_id}/promo-codes.

Security
oauth2
Path
cart_idstring(uuid)required

Unique identifier for the cart.

Query
codestring<= 30 charactersrequired

The promo code to validate (case-insensitive).

Example: code=SUMMER25
curl -i -X GET \
  'https://developers.tote.ai/_mock/online-ordering/spec/openapi/carts/{cart_id}/promo-codes/validate?code=SUMMER25' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Validation result with discount preview or rejection reason.

Bodyapplication/json
codestringrequired

The promo code, normalized to uppercase. Always returned as uppercase regardless of input casing.

Example: "SUMMER25"
validbooleanrequired

Whether the code is valid for this cart. When true, discount_preview contains the estimated discount. When false, rejection_reason and rejection_message explain why.

discount_previewobject or null

Estimated discount this code would provide if applied. Present when valid is true. Null when valid is false.

rejection_reasonstring or null

Machine-readable reason why the code is invalid. Present when valid is false. Null when valid is true.

  • INVALID_CODE: The code does not exist or is not recognized.
  • EXPIRED: The code has passed its expiration date.
  • ALREADY_USED: The code has already been redeemed (single-use codes).
  • MINIMUM_NOT_MET: The cart does not meet the minimum order amount for this code.
  • NOT_APPLICABLE: No items in the cart are eligible for this code.
  • ALREADY_APPLIED: A promo code is already active on this cart. Remove it first.
Enum"INVALID_CODE""EXPIRED""ALREADY_USED""MINIMUM_NOT_MET""NOT_APPLICABLE""ALREADY_APPLIED"null
rejection_messagestring or null

Human-readable rejection message. Present when valid is false. Safe to display to the end user.

Example: "This promo code has expired."
Response
application/json
{
  "code": "SUMMER25",
  "valid": true,
  "discount_preview": {
    "estimated_discount": { … },
    "description": "25% off your order (up to $10)",
    "applicable_items": []
  },
  "rejection_reason": null,
  "rejection_message": null
}

Remove a promo code from a cart

Request

Removes the specified promo code from the cart. The associated discount is removed and totals are recalculated. Returns the updated Cart with the promo removed from promo_codes and the discount removed from totals.

The code path parameter is case-insensitive -- the server normalizes it before matching.

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.

codestringrequired

The promo code to remove (case-insensitive).

Example: SUMMER25
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}/promo-codes/SUMMER25' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Idempotency-Key: d7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23'

Responses

Promo code removed. Returns the updated cart without the promo.

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

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