Skip to content
API Reference
/
/
Stock updated event

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 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.

Stock updated eventWebhook

Request

Sent when item availability changes at a location. A single event can contain multiple items. Use GET /locations/{location_id}/inventory as a polling fallback.

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 "stock.updated"
created_atstring(date-time)required

When the event occurred (ISO 8601 UTC).

dataobjectrequired

Stock change details. Use GET /locations/{location_id}/inventory as a polling fallback to reconcile.

data.​location_idstring(uuid)required

The location where stock changed.

data.​itemsArray of objectsnon-emptyrequired

Items whose availability status changed. A single event can report multiple item changes at the same location.

data.​items[].​item_idstring(uuid)required

Unique identifier for the menu item.

data.​items[].​namestringrequired

Item name for display/logging convenience.

data.​items[].​previous_statusstring(AvailabilityStatus)required

Item availability status at a location.

  • IN_STOCK: Item is available for ordering.
  • LOW_STOCK: Item is available but quantities are limited. The threshold for LOW_STOCK is configured server-side per location.
  • OUT_OF_STOCK: Item is not available for ordering. Do not display this item as orderable to customers.
Enum"IN_STOCK""LOW_STOCK""OUT_OF_STOCK"
data.​items[].​current_statusstring(AvailabilityStatus)required

Item availability status at a location.

  • IN_STOCK: Item is available for ordering.
  • LOW_STOCK: Item is available but quantities are limited. The threshold for LOW_STOCK is configured server-side per location.
  • OUT_OF_STOCK: Item is not available for ordering. Do not display this item as orderable to customers.
Enum"IN_STOCK""LOW_STOCK""OUT_OF_STOCK"
data.​items[].​updated_atstring(date-time)required

When this item's stock status changed.

application/json
{
  "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7",
  "event_type": "stock.updated",
  "created_at": "2019-08-24T14:15:22Z",
  "data": {
    "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
    "items": [ … ]
  }
}

Responses

Event received successfully.

Menu changed eventWebhook

Request

Sent when a location's menu is modified. Re-fetch the full menu via GET /locations/{location_id}/menu. Use version_hash to avoid unnecessary re-fetches.

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 "menu.changed"
created_atstring(date-time)required

When the event occurred (ISO 8601 UTC).

dataobjectrequired

Menu change details. Re-fetch the full menu via GET /locations/{location_id}/menu after receiving this event.

data.​location_idstring(uuid)required

The location whose menu changed.

data.​version_hashstringrequired

New menu version hash. Compare with your cached version to determine if a re-fetch is needed. Matches the version_hash field from GET /locations/{location_id}/menu/metadata.

Example: "sha256:b2c3d4e5f6a7"
data.​change_typestringrequired

The type of menu change that occurred.

  • ITEMS_ADDED: New items added to the menu.
  • ITEMS_REMOVED: Items removed from the menu.
  • ITEMS_MODIFIED: Existing items changed (price, name, modifiers, etc.).
  • CATEGORIES_CHANGED: Category structure modified (added, removed, reordered).
  • FULL_UPDATE: Bulk menu update affecting multiple aspects.
Enum"ITEMS_ADDED""ITEMS_REMOVED""ITEMS_MODIFIED""CATEGORIES_CHANGED""FULL_UPDATE"
data.​changed_atstring(date-time)required

When the menu change occurred.

application/json
{
  "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7",
  "event_type": "menu.changed",
  "created_at": "2019-08-24T14:15:22Z",
  "data": {
    "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
    "version_hash": "sha256:b2c3d4e5f6a7",
    "change_type": "ITEMS_ADDED",
    "changed_at": "2019-08-24T14:15:22Z"
  }
}

Responses

Event received successfully.