Skip to content
/Webhook Subscriptions

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

Create a webhook subscription

Request

Register an HTTPS endpoint to receive webhook events. You can create multiple subscriptions to route different event types to different URLs.

Signing secret: The response includes a signing_secret field that is ONLY returned in this response. Store it securely -- it cannot be retrieved again. Use it to verify the X-Tote-Signature header on incoming webhook deliveries.

Idempotency: This endpoint requires the Idempotency-Key header. If a request with the same key is received within 24 hours, the server returns the cached response without creating a duplicate subscription.

Security
oauth2
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
Bodyapplication/jsonrequired
urlstring(uri)required

HTTPS URL to receive webhook events. Must use HTTPS -- HTTP URLs are rejected with a 422 error.

event_typesArray of stringsnon-emptyrequired

Event types this subscription should receive. At least one event type is required.

Items Enum"order.created""order.status_changed""order.cancelled""stock.updated""menu.changed""location.hours_changed"
curl -i -X POST \
  https://developers.tote.ai/_mock/online-ordering/spec/openapi/webhooks \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: d7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23' \
  -d '{
    "url": "https://your-app.com/webhooks/tote",
    "event_types": [
      "order.created",
      "order.status_changed",
      "order.cancelled",
      "stock.updated"
    ]
  }'

Responses

Webhook subscription created. The signing_secret is included in this response only -- store it securely.

Bodyapplication/json
idstring(uuid)required

Unique identifier for this webhook subscription.

urlstring(uri)required

The HTTPS URL that receives webhook event deliveries.

event_typesArray of stringsnon-emptyrequired

Event types this subscription receives. Only events matching these types are delivered to the subscription URL.

Items Enum"order.created""order.status_changed""order.cancelled""stock.updated""menu.changed""location.hours_changed"
statusstringrequired

Subscription status.

  • ACTIVE: Subscription is receiving events normally.
  • DISABLED: Subscription has been disabled due to consecutive delivery failures. Create a new subscription or contact support to re-enable.
Enum"ACTIVE""DISABLED"
created_atstring(date-time)required

When the subscription was created.

Response
application/json
{
  "id": "wh_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://your-app.com/webhooks/tote",
  "event_types": [
    "order.created",
    "order.status_changed",
    "order.cancelled",
    "stock.updated"
  ],
  "status": "ACTIVE",
  "signing_secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "created_at": "2026-02-01T10:00:00Z"
}

List webhook subscriptions

Request

Returns all webhook subscriptions for the authenticated partner. Results are ordered by creation date (newest first).

Note: The signing_secret field is NOT included in list responses. It is only returned when a subscription is first created via POST.

Pagination: Results use cursor-based pagination. Use the cursor parameter from the pagination.next_cursor field to retrieve the next page.

Security
oauth2
Query
cursorstring

Opaque cursor for pagination. Obtained from the next_cursor field of a previous response.

limitinteger[ 1 .. 100 ]

Maximum number of results to return per page.

Default 20
curl -i -X GET \
  'https://developers.tote.ai/_mock/online-ordering/spec/openapi/webhooks?cursor=string&limit=20' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

A paginated list of webhook subscriptions.

Bodyapplication/json
dataArray of objects(WebhookSubscription)required

List of webhook subscriptions.

data[].​idstring(uuid)required

Unique identifier for this webhook subscription.

data[].​urlstring(uri)required

The HTTPS URL that receives webhook event deliveries.

data[].​event_typesArray of stringsnon-emptyrequired

Event types this subscription receives. Only events matching these types are delivered to the subscription URL.

Items Enum"order.created""order.status_changed""order.cancelled""stock.updated""menu.changed""location.hours_changed"
data[].​statusstringrequired

Subscription status.

  • ACTIVE: Subscription is receiving events normally.
  • DISABLED: Subscription has been disabled due to consecutive delivery failures. Create a new subscription or contact support to re-enable.
Enum"ACTIVE""DISABLED"
data[].​created_atstring(date-time)required

When the subscription was created.

paginationobject(Pagination)required
pagination.​has_morebooleanrequired

Whether more results exist beyond this page.

pagination.​next_cursorstring or null

Opaque cursor for the next page. Pass as the cursor query parameter. Null when there are no more results.

Response
application/json
{
  "data": [
    { … },
    { … }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

Delete a webhook subscription

Request

Permanently removes a webhook subscription. Events will no longer be delivered to the subscription URL. This action cannot be undone.

After deletion, any in-flight deliveries for this subscription may still arrive at the endpoint. Your webhook handler should gracefully ignore events for unknown subscriptions.

Security
oauth2
Path
webhook_idstring(uuid)required

Unique identifier for the webhook subscription.

curl -i -X DELETE \
  'https://developers.tote.ai/_mock/online-ordering/spec/openapi/webhooks/{webhook_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Webhook subscription deleted successfully.

Response
No content

Inventory

Item availability and stock status.

Operations

Events

Webhook event payloads delivered to your subscription URLs.

Webhooks