OAuth 2.0 client credentials token management.
API Reference
/- Calculate cart prices
Create a new cart
Get cart details
Abandon a cart
Update cart properties
Add an item to the cart
Update a cart item
Remove an item from the cart
Check out a cart
Set or update the cart's handoff mode
Apply a promo code to a cart
List promo codes on a cart
Validate a promo code without applying
Remove a promo code from a cart
Calculate cart prices
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.
Download OpenAPI description
Overview
Tote Developer Support
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
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.
Security
oauth2
Headers
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
- 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.
Example: "CUST-12345"
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"
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").
Default 1
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.
Default false
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.
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 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.
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" }
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.
Security
oauth2
- 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).
Default false
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.
Response
application/json
{ "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" }
Request
Converts an ACTIVE cart into an order. The cart must have at least one item and a handoff mode must be available (either stored on the cart via PUT /carts/{cart_id}/handoff, or provided as an override in the request body).
Validation performed at checkout:
- Cart is in ACTIVE status
- Cart has at least one item
- All items are still available in the current menu
- Modifier selections satisfy group constraints (min/max)
- Handoff mode exists (stored on cart OR provided in request body)
Age verification: If the cart contains age-restricted items, checkout succeeds but the response includes age_verification_required: true and an age_verification_notice explaining that the consumer will be verified at pickup or delivery.
Price changes: If expected_total is provided and the current total differs, the server returns 409 Conflict. Omit expected_total to accept the current price.
After successful checkout, the cart status changes to CHECKED_OUT and can no longer be modified. The created order is returned with status PENDING.
Idempotency: This endpoint supports idempotent requests. Include an Idempotency-Key header (UUID v4) to safely retry requests. If the cart has already been checked out with the same idempotency key, the original order is returned.
Security
oauth2
Headers
Bodyapplication/jsonrequiredA 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
One of:
Optional override for the handoff mode. If provided, this replaces the cart's stored handoff mode for this checkout. If omitted, the cart's stored handoff mode is used.
At checkout, a handoff mode must exist either on the cart (set via PUT /carts/{cart_id}/handoff) or in this field. If neither is present, the server returns 422.
Optional optimistic concurrency check. If provided (in cents), the server compares this against the current calculated total. If they don't match (e.g., prices changed since the last calculate call), the server returns 409 Conflict instead of proceeding with checkout.
Omit this field to skip the total verification and proceed with the current price.
- Mock serverhttps://developers.tote.ai/_mock/online-ordering/spec/openapi/carts/{cart_id}/checkout
- Production (placeholder -- use your assigned base URL)https://api.tote.ai/v1/online-ordering/carts/{cart_id}/checkout
- Sandbox (placeholder -- use your assigned base URL)https://sandbox.api.tote.ai/v1/online-ordering/carts/{cart_id}/checkout
- 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}/checkout' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: d7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23' \
-d '{
"handoff_mode": {
"mode": "CURBSIDE",
"vehicle_make": "Toyota",
"vehicle_model": "Camry",
"vehicle_color": "Silver",
"pickup_time": null
},
"expected_total": 1945,
"notes": null
}'Order created successfully. The cart status is now CHECKED_OUT.
Customer identifier from the cart at checkout time. Null for anonymous orders. Locked at checkout -- cannot be changed after the order is created.
Example: "CUST-12345"
Order lifecycle status. Tracks the high-level state of the order from creation through completion or cancellation.
- PENDING: Order created from cart checkout, awaiting payment.
- CONFIRMED: At least one payment completed; order accepted by the store.
- COMPLETED: Order fulfilled and closed.
- FAILED: Order could not be processed (e.g., all payments failed).
- VOIDED: Order voided before any fulfillment began.
- CANCELLED: Order cancelled by customer or system.
State transitions:
- PENDING -> CONFIRMED, FAILED, VOIDED, CANCELLED
- CONFIRMED -> COMPLETED, CANCELLED
- COMPLETED, FAILED, VOIDED, CANCELLED are terminal (no further transitions)
Enum"PENDING""CONFIRMED""COMPLETED""FAILED""VOIDED""CANCELLED"
Aggregate payment status across all payments on the order. This is a server-computed summary -- do not set directly.
- UNPAID: No payments submitted yet.
- PROCESSING: At least one payment is in a non-terminal state (PENDING or AUTHORIZED).
- PARTIALLY_PAID: Some payments completed but total paid < order total.
- PAID: Total paid >= order total. The order is fully covered.
State transitions:
- UNPAID -> PROCESSING, PARTIALLY_PAID, PAID
- PROCESSING -> PARTIALLY_PAID, PAID, UNPAID (if all payments fail)
- PARTIALLY_PAID -> PROCESSING, PAID
- PAID is terminal for forward flow (refunds revert to PARTIALLY_PAID or UNPAID)
Enum"UNPAID""PROCESSING""PARTIALLY_PAID""PAID"
Fulfillment lifecycle status. Tracks the physical preparation and handoff of the order. Maps directly from the backend fulfillment state machine.
- PENDING: Order created, not yet accepted by store.
- IN_PROGRESS: Store accepted the order and is queuing it.
- PREPARING: Store staff actively assembling the order.
- READY_FOR_PICKUP: Order assembled and waiting for customer (pickup/curbside).
- FULFILLED: Customer received the order (pickup/curbside/kiosk).
- DELIVERED: Order delivered to customer address (delivery orders).
- RETURNED: Order returned after fulfillment.
- CANCELLED: Fulfillment cancelled before completion.
State transitions:
- PENDING -> IN_PROGRESS, CANCELLED
- IN_PROGRESS -> PREPARING, CANCELLED
- PREPARING -> READY_FOR_PICKUP, CANCELLED
- READY_FOR_PICKUP -> FULFILLED, DELIVERED, CANCELLED
- FULFILLED -> RETURNED
- DELIVERED -> RETURNED
- RETURNED, CANCELLED are terminal (no further transitions)
Cancellation restriction: Orders can only be cancelled via POST /orders/{order_id}/cancel when fulfillment_status is PENDING or IN_PROGRESS. Once preparation begins, cancellation requires store intervention.
Enum"PENDING""IN_PROGRESS""PREPARING""READY_FOR_PICKUP""FULFILLED""DELIVERED""RETURNED""CANCELLED"
Line items in the order (locked at checkout).
Base price per unit (locked at checkout).
Total price of all selected modifiers per unit (locked at checkout).
Total for this line item: (base_price + modifier_total) * quantity. Locked at checkout.
Modifiers selected for this item (locked at checkout).
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").
Default 1
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, locked at checkout. Null if none were provided.
True if this item requires age verification. Copied from the menu item at checkout time.
Default false
Payments attached to this order. Empty array until the first payment is submitted via POST /orders/{order_id}/payments.
Payment processing status. The typical online ordering flow is: PENDING -> COMPLETED (immediate capture).
For pre-authorization flows: PENDING -> AUTHORIZED -> CAPTURED -> COMPLETED.
Terminal states: COMPLETED, VOIDED, REFUNDED, FAILED.
State transitions:
- PENDING -> AUTHORIZED, COMPLETED, FAILED
- AUTHORIZED -> CAPTURED, VOIDED, FAILED
- CAPTURED -> COMPLETED, REFUNDED, PARTIALLY_REFUNDED
- COMPLETED -> REFUNDED, PARTIALLY_REFUNDED
- VOIDED, REFUNDED, FAILED are terminal (no further transitions)
- PARTIALLY_REFUNDED -> REFUNDED (when remaining amount is refunded)
Enum"PENDING""AUTHORIZED""CAPTURED""COMPLETED""VOIDED""REFUNDED""PARTIALLY_REFUNDED""FAILED"
The payment method used. These are the API-facing values; the server maps them to internal payment processing types.
- CREDIT_CARD: Visa, Mastercard, Amex, Discover credit cards
- DEBIT_CARD: Debit cards with PIN or signature
- CASH: Customer pays cash at the pickup counter. Only meaningful for PICKUP and DINE_IN handoff modes. The order is submitted online but payment is collected in-store.
- GIFT_CARD: Store gift cards or third-party gift cards
- LOYALTY_POINTS: Loyalty program points redeemed as payment
- DIGITAL_WALLET: Apple Pay, Google Pay, or other digital wallets
- EBT: SNAP/EBT card. Item eligibility applies -- only SNAP-eligible items (generally food items, excluding hot prepared foods and tobacco) can be paid with EBT. Check
allowed_tenderson each menu item.
Tolerant Reader: New payment method values may be added in future API versions. Your integration should handle unknown enum values gracefully (e.g., log a warning and skip) rather than failing.
Enum"CREDIT_CARD""DEBIT_CARD""CASH""GIFT_CARD""LOYALTY_POINTS""DIGITAL_WALLET""EBT"
The payment amount in cents.
Tip amount included in this payment, if any. Null if no tip.
One of:
Tip amount included in this payment, if any. Null if no tip.
Method-specific details. Shape varies by payment_method:
- CREDIT_CARD / DEBIT_CARD:
{ "last_four": "4242", "brand": "visa", "exp_month": 12, "exp_year": 2027 } - GIFT_CARD:
{ "last_four": "7890", "balance_remaining": { "amount": 1500, "currency": "USD" } } - LOYALTY_POINTS:
{ "points_used": 500, "points_remaining": 1200 } - DIGITAL_WALLET:
{ "wallet_type": "apple_pay" }
Promo codes that were active on the cart at checkout (locked at checkout).
Customer notes from checkout (e.g., "No onions please"). Null if no notes were provided.
Sum of all item totals before tax and discounts.
Total tax amount for the order.
Total of cart-level discounts applied to the order (locked at checkout). Item-level discounts are reflected in each item's total.
Grand total: subtotal + total_tax + total_fees - total_discount. Locked at checkout.
Sum of all completed payment amounts. Updated as payments reach COMPLETED status.
Remaining amount to be paid (total - total_paid). Zero when the order is fully paid.
True if any item requires age verification. When true, the consumer will be verified at pickup or delivery (offline verification).
Default false
Human-readable notice about age verification requirements. Null when no age-restricted items are in the order.
Estimated time the order will be ready for pickup or delivery, as an ISO 8601 datetime (e.g., "2026-03-15T14:30:00-05:00"). Null when the estimate is not yet available (e.g., before the order is confirmed by the store). Updated as the order progresses -- poll the order or listen for order.status.changed webhooks to get updated estimates.
Response
application/json
{ "id": "f9a8b7c6-d5e4-3210-fedc-ba9876543210", "cart_id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab", "location_id": "b5a7c8d9-e0f1-4a2b-8c3d-4e5f6a7b8c9d", "status": "PENDING", "payment_status": "UNPAID", "fulfillment_status": "PENDING", "items": [ { … }, { … } ], "payments": [], "discounts": [], "handoff": { "mode": "CURBSIDE", "vehicle_make": "Toyota", "vehicle_model": "Camry", "vehicle_color": "Silver", "pickup_time": null }, "notes": null, "subtotal": { "amount": 1797, "currency": "USD" }, "total_tax": { "amount": 148, "currency": "USD" }, "total_discount": { "amount": 0, "currency": "USD" }, "total": { "amount": 1945, "currency": "USD" }, "total_paid": { "amount": 0, "currency": "USD" }, "balance_due": { "amount": 1945, "currency": "USD" }, "age_verification_required": false, "age_verification_notice": null, "created_at": "2026-01-31T10:07:00Z", "updated_at": "2026-01-31T10:07:00Z" }