OAuth 2.0 client credentials token management.
- Remove an item from 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.
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
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.
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.
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.
ID of the menu item to add (from GET /locations/{location_id}/menu). The server validates that this item exists and is available.
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.
- Mock serverhttps://developers.tote.ai/_mock/online-ordering/spec/openapi/carts/{cart_id}/items/{item_id}
- Production (placeholder -- use your assigned base URL)https://api.tote.ai/v1/online-ordering/carts/{cart_id}/items/{item_id}
- Sandbox (placeholder -- use your assigned base URL)https://sandbox.api.tote.ai/v1/online-ordering/carts/{cart_id}/items/{item_id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
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"
}'Cart item updated. Returns the updated cart.
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.
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.
Line items in the cart.
Reference to the menu item (from GET /locations/{location_id}/menu).
Base price per unit (from the menu item).
Total price of all selected modifiers per unit.
Total for this line item: (base_price + modifier_total) * quantity.
Modifiers selected for this item.
ID of the modifier group this selection belongs to.
ID of the selected modifier within the group.
Quantity of this modifier. Relevant for modifier groups with allows_duplicates: true (e.g., "Extra Cheese x2").
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.
Customer's special instructions for this item (e.g., "no onions", "extra ice"). Null if none were provided. Max 200 characters.
True if this specific item requires age verification. Copied from the menu item's age_verification_required flag.
The handoff mode set for this cart, or null if not yet selected. Set via PUT /carts/{cart_id}/handoff. Required before checkout.
The handoff mode set for this cart, or null if not yet selected. Set via PUT /carts/{cart_id}/handoff. Required before checkout.
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.
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.
Sum of all item totals before tax and discounts.
Total tax amount for the cart.
Total of cart-level discounts applied to the cart. Item-level discounts are reflected in each item's total.
Fees currently applied to this cart. Recalculated on each cart modification. Call POST /carts/{cart_id}/calculate for the authoritative fee breakdown.
Grand total: subtotal + total_tax + total_fees - total_discount.
{ "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" }
Request
Removes a specific item from the cart. 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.
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.
- Mock serverhttps://developers.tote.ai/_mock/online-ordering/spec/openapi/carts/{cart_id}/items/{item_id}
- Production (placeholder -- use your assigned base URL)https://api.tote.ai/v1/online-ordering/carts/{cart_id}/items/{item_id}
- Sandbox (placeholder -- use your assigned base URL)https://sandbox.api.tote.ai/v1/online-ordering/carts/{cart_id}/items/{item_id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X DELETE \
'https://developers.tote.ai/_mock/online-ordering/spec/openapi/carts/{cart_id}/items/{item_id}' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Idempotency-Key: d7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23'Cart item removed. Returns the updated cart.
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.
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.
Line items in the cart.
Reference to the menu item (from GET /locations/{location_id}/menu).
Base price per unit (from the menu item).
Total price of all selected modifiers per unit.
Total for this line item: (base_price + modifier_total) * quantity.
Modifiers selected for this item.
ID of the modifier group this selection belongs to.
ID of the selected modifier within the group.
Quantity of this modifier. Relevant for modifier groups with allows_duplicates: true (e.g., "Extra Cheese x2").
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.
Customer's special instructions for this item (e.g., "no onions", "extra ice"). Null if none were provided. Max 200 characters.
True if this specific item requires age verification. Copied from the menu item's age_verification_required flag.
The handoff mode set for this cart, or null if not yet selected. Set via PUT /carts/{cart_id}/handoff. Required before checkout.
The handoff mode set for this cart, or null if not yet selected. Set via PUT /carts/{cart_id}/handoff. Required before checkout.
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.
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.
Sum of all item totals before tax and discounts.
Total tax amount for the cart.
Total of cart-level discounts applied to the cart. Item-level discounts are reflected in each item's total.
Fees currently applied to this cart. Recalculated on each cart modification. Call POST /carts/{cart_id}/calculate for the authoritative fee breakdown.
Grand total: subtotal + total_tax + total_fees - total_discount.
{ "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" }
Request
Returns an itemized price breakdown for the cart without creating or modifying an order. This is a read-only preview -- it computes prices at request time based on the current menu, tax configuration, and applicable discounts.
Important: Prices may change between calculate and checkout if the menu or tax configuration is updated. Always call calculate immediately before checkout to show the customer the most accurate total.
This endpoint is analogous to Square's CalculateOrder and Toast's /prices endpoint.
- Mock serverhttps://developers.tote.ai/_mock/online-ordering/spec/openapi/carts/{cart_id}/calculate
- Production (placeholder -- use your assigned base URL)https://api.tote.ai/v1/online-ordering/carts/{cart_id}/calculate
- Sandbox (placeholder -- use your assigned base URL)https://sandbox.api.tote.ai/v1/online-ordering/carts/{cart_id}/calculate
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://developers.tote.ai/_mock/online-ordering/spec/openapi/carts/{cart_id}/calculate' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'Price calculation completed.
Price breakdown for each cart item.
Base price per unit.
Total modifier cost per unit.
Item-level discounts applied to this line item.
Subtotal for this line: (base_price + modifier_total) * quantity - item-level discounts. Item-level discounts are already deducted here, so the cart-level total_discount on PriceCalculation does not include them.
Tax amount for this line item.
Total for this line item including tax: item_subtotal + item_tax.
Cart-level discounts applied to the order. Item-level discounts appear on each line item in the line_items array, not here. Each discount is listed as a separate line item with name, type, source, and amount deducted.
Promo codes active on the cart. Their discounts appear in the discounts array with source: PROMO_CODE.
Whether member-specific pricing was applied during this calculation. True when the cart has a customer_id and the server found matching member pricing rules. False when the cart is anonymous or when the customer_id has no associated member pricing.
Use this field to show customers whether they are receiving member prices (e.g., "Member pricing applied" badge in your UI).
Fees applied to this order (delivery, service, bag, small order surcharge). Each fee is a separate line item. Display all fees to the customer.
Sum of all line item subtotals (before tax, after item-level discounts).
Total tax for the entire cart.
Sum of cart-level discount amounts. Item-level discounts are already deducted from each line item's item_subtotal and are NOT included in this field. This avoids double-counting.
Sum of all fee amounts. Included in the total formula.
The amount on which tax was computed. Equals subtotal minus any pre-tax cart-level discounts plus taxable fee amounts. Exposed for transparency so partners can verify tax calculations independently.
Grand total: subtotal + total_tax + total_fees - total_discount.
True if any item in the cart requires age verification. This is informational -- the consumer will be verified at pickup or delivery.
{ "cart_id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab", "currency": "USD", "line_items": [ { … }, { … } ], "discounts": [], "fees": [], "subtotal": { "amount": 1797, "currency": "USD" }, "total_tax": { "amount": 148, "currency": "USD" }, "total_discount": { "amount": 0, "currency": "USD" }, "total_fees": { "amount": 0, "currency": "USD" }, "taxable_amount": { "amount": 1797, "currency": "USD" }, "total": { "amount": 1945, "currency": "USD" }, "age_verification_required": false, "calculated_at": "2026-01-31T10:06:00Z" }