Skip to content
/Events

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

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

Order created eventWebhook

Request

Sent when a new order is placed via checkout. Contains minimal order data -- fetch the full order via GET /orders/{order_id}.

Bodyapplication/json
event_idstring(uuid)required

Unique identifier for this event. Use for idempotent processing.

event_typestringrequired

The type of event that occurred. Determines the shape of the data field.

Value "order.created"
created_atstring(date-time)required

When the event occurred (ISO 8601 UTC).

dataobjectrequired

Minimal order data. Fetch the full order via GET /orders/{order_id} for complete details.

data.​order_idstring(uuid)required

Unique identifier for the created order.

data.​location_idstring(uuid)required

The location (store) this order belongs to.

data.​statusstring(OrderStatus)required

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"
data.​handoff_modestringrequired

The handoff mode selected for this order.

Enum"PICKUP""CURBSIDE""DELIVERY""KIOSK"
data.​totalobject(Money)required

Grand total for the order.

data.​total.​amountintegerrequired

Monetary value in the smallest currency unit (cents for USD). Example: 1299 = $12.99.

Example: 1299
data.​total.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
data.​created_atstring(date-time)required

When the order was created (checkout time).

application/json
{
  "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7",
  "event_type": "order.created",
  "created_at": "2019-08-24T14:15:22Z",
  "data": {
    "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
    "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
    "status": "PENDING",
    "handoff_mode": "PICKUP",
    "total": { … },
    "created_at": "2019-08-24T14:15:22Z"
  }
}

Responses

Event received successfully.

Order status changed eventWebhook

Request

Sent when any of the order's three status fields change (lifecycle status, fulfillment status, or payment status). Includes previous and current values for all three fields.

Bodyapplication/json
event_idstring(uuid)required

Unique identifier for this event. Use for idempotent processing.

event_typestringrequired

The type of event that occurred. Determines the shape of the data field.

Value "order.status_changed"
created_atstring(date-time)required

When the event occurred (ISO 8601 UTC).

dataobjectrequired

Event-specific payload. Shape depends on event_type. See individual event schemas for details.

data.​order_idstring(uuid)required

Unique identifier for the order.

data.​location_idstring(uuid)required

The location (store) this order belongs to.

data.​previous_statusstring(OrderStatus)required

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"
data.​current_statusstring(OrderStatus)required

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"
data.​previous_fulfillment_statusstring(FulfillmentStatus)required

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"
data.​current_fulfillment_statusstring(FulfillmentStatus)required

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"
data.​previous_payment_statusstring(OrderPaymentStatus)required

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"
data.​current_payment_statusstring(OrderPaymentStatus)required

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"
data.​updated_atstring(date-time)required

When the status change occurred.

application/json
{
  "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7",
  "event_type": "order.status_changed",
  "created_at": "2019-08-24T14:15:22Z",
  "data": {
    "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
    "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
    "previous_status": "PENDING",
    "current_status": "PENDING",
    "previous_fulfillment_status": "PENDING",
    "current_fulfillment_status": "PENDING",
    "previous_payment_status": "UNPAID",
    "current_payment_status": "UNPAID",
    "updated_at": "2019-08-24T14:15:22Z"
  }
}

Responses

Event received successfully.

Order cancelled eventWebhook

Request

Sent when an order is cancelled. Includes cancellation reason if provided. Any pending payments are voided and completed payments are refunded.

Bodyapplication/json
event_idstring(uuid)required

Unique identifier for this event. Use for idempotent processing.

event_typestringrequired

The type of event that occurred. Determines the shape of the data field.

Value "order.cancelled"
created_atstring(date-time)required

When the event occurred (ISO 8601 UTC).

dataobjectrequired

Event-specific payload. Shape depends on event_type. See individual event schemas for details.

data.​order_idstring(uuid)required

Unique identifier for the cancelled order.

data.​location_idstring(uuid)required

The location (store) this order belongs to.

data.​reasonstring or null<= 500 characters

Human-readable cancellation reason. Null if no reason was provided.

data.​cancelled_atstring(date-time)required

When the order was cancelled.

application/json
{
  "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7",
  "event_type": "order.cancelled",
  "created_at": "2019-08-24T14:15:22Z",
  "data": {
    "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
    "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
    "reason": "string",
    "cancelled_at": "2019-08-24T14:15:22Z"
  }
}

Responses

Event received successfully.