OAuth 2.0 client credentials token management.
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
Returns the full order resource including line items, payments, all three status fields, financial totals, and handoff details.
Status fields:
status: Order lifecycle (PENDING, CONFIRMED, COMPLETED, etc.)payment_status: Aggregate payment state (UNPAID, PROCESSING, PARTIALLY_PAID, PAID)fulfillment_status: Physical fulfillment progress (PENDING through FULFILLED/DELIVERED)
Polling for updates: After submitting a payment, poll this endpoint to check the updated payment_status and balance_due. Recommended polling interval: 2 seconds, with exponential backoff up to 30 seconds. Stop polling when payment_status reaches PAID or the payment reaches a terminal state.
Payments array: The payments array contains all payments attached to this order, including their individual statuses. Use this to display payment history and determine if additional payments are needed for split-pay scenarios.
Security
oauth2
- Mock serverhttps://developers.tote.ai/_mock/online-ordering/spec/openapi/orders/{order_id}
- Production (placeholder -- use your assigned base URL)https://api.tote.ai/v1/online-ordering/orders/{order_id}
- Sandbox (placeholder -- use your assigned base URL)https://sandbox.api.tote.ai/v1/online-ordering/orders/{order_id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://developers.tote.ai/_mock/online-ordering/spec/openapi/orders/{order_id}' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'The full order resource.
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": "CONFIRMED", "payment_status": "PAID", "fulfillment_status": "PREPARING", "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": 1945, "currency": "USD" }, "balance_due": { "amount": 0, "currency": "USD" }, "age_verification_required": false, "age_verification_notice": null, "created_at": "2026-01-31T10:07:00Z", "updated_at": "2026-01-31T10:09:00Z" }
Request
Cancels an order that has not yet started preparation. This endpoint is only available when fulfillment_status is PENDING or IN_PROGRESS.
Fulfillment restriction: Once the store begins preparing the order (fulfillment_status is PREPARING or later), this endpoint returns 409 Conflict. Cancellation at that stage requires store intervention.
Automatic void/refund: When an order is cancelled, the server automatically handles all attached payments:
- Payments in PENDING or AUTHORIZED status are voided (no charge).
- Payments in CAPTURED or COMPLETED status are refunded in full.
- Refunds follow the minimize-cash-refund strategy: loyalty points are refunded first, then gift cards, then credit/debit cards.
No separate refund request is needed after cancellation.
Idempotency: This endpoint requires the Idempotency-Key header. If the order was already cancelled with the same key, the server returns the current order state without re-processing.
Result: The order's status is set to CANCELLED, fulfillment_status is set to CANCELLED, and all payments are voided or refunded.
Security
oauth2
Headers
Bodyapplication/jsonA 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/orders/{order_id}/cancel
- Production (placeholder -- use your assigned base URL)https://api.tote.ai/v1/online-ordering/orders/{order_id}/cancel
- Sandbox (placeholder -- use your assigned base URL)https://sandbox.api.tote.ai/v1/online-ordering/orders/{order_id}/cancel
- 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/orders/{order_id}/cancel' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: d7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23' \
-d '{
"reason": "Customer changed their mind"
}'Order cancelled successfully. Returns the updated order with status CANCELLED and all payments voided/refunded.
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": "CANCELLED", "payment_status": "UNPAID", "fulfillment_status": "CANCELLED", "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:15:00Z" }