Skip to content
/Locations

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

List all locations

Request

Returns a paginated list of locations accessible to your API credentials. Use the online_ordering_enabled field to filter locations that accept online orders.

Pagination: Results are returned in pages. Use the cursor parameter from the pagination.next_cursor field to retrieve the next page.

Security
oauth2
Query
limitinteger[ 1 .. 100 ]

Maximum number of results to return per page.

Default 20
cursorstring

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

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

Responses

A paginated list of locations.

Bodyapplication/json
dataArray of objects(Location)required

List of locations.

data[].​idstring(uuid)required

Unique identifier for this location.

data[].​namestringrequired

Store name (e.g., "QuickStop

Example: "QuickStop #247"
data[].​addressobjectrequired
data[].​address.​streetstringrequired

Street address.

Example: "4521 Congress Ave"
data[].​address.​citystringrequired

City name.

Example: "Austin"
data[].​address.​statestring= 2 charactersrequired

Two-letter state code (e.g., "TX").

Example: "TX"
data[].​address.​postal_codestringrequired

ZIP or postal code.

Example: "78745"
data[].​address.​countrystringrequired

Two-letter ISO 3166-1 alpha-2 country code.

Default "US"
Example: "US"
data[].​phonestring

Store phone number in E.164 format (e.g., "+15125551234").

Example: "+15125551234"
data[].​latitudenumber or null(double)

Latitude in decimal degrees (WGS 84 datum). Null if the location has not been geocoded. Use with longitude for store locator features and distance calculations.

Example: 30.2277
data[].​longitudenumber or null(double)

Longitude in decimal degrees (WGS 84 datum). Null if the location has not been geocoded.

Example: -97.7553
data[].​timezonestringrequired

IANA timezone identifier for this location. Used to interpret business_hours and daily_sales_start_time/end_time fields.

Example: "America/Chicago"
data[].​online_ordering_enabledbooleanrequired

Whether this location currently accepts online orders. Only locations with online_ordering_enabled=true should be displayed to customers.

data[].​default_prep_time_minutesinteger or null

Default estimated preparation time in minutes for orders at this location. Used to compute estimated_ready_at on orders when no item-specific prep time applies. Null if the location has not configured a default.

Example: 15
data[].​minimum_order_amountsobject or null

Minimum order subtotal required per handoff mode. If a customer's cart subtotal is below the minimum for their selected handoff mode, the server automatically applies a SMALL_ORDER fee covering the shortfall rather than blocking the order. Null if no minimums are configured.

Keys are lowercase handoff mode identifiers. Only modes with minimums are present -- absence means no minimum for that mode.

Example: {"delivery":{"amount":1500,"currency":"USD"},"pickup":{"amount":500,"currency":"USD"}}
data[].​business_hoursArray of objects

Weekly business hours for this location. One entry per day of the week. Hours are in the location's local timezone.

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": true,
    "next_cursor": "eyJpZCI6ImIyYzNkNGU1LWY2YTctODkwMS1iY2RlLWYxMjM0NTY3ODkwMSJ9"
  }
}

Get a location by ID

Request

Returns a single location by its unique identifier. The response includes the full location details including address, business hours, and whether online ordering is enabled.

Security
oauth2
Path
location_idstring(uuid)required

Unique identifier for the location.

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

Responses

The requested location.

Bodyapplication/json
idstring(uuid)required

Unique identifier for this location.

namestringrequired

Store name (e.g., "QuickStop

Example: "QuickStop #247"
addressobjectrequired
address.​streetstringrequired

Street address.

Example: "4521 Congress Ave"
address.​citystringrequired

City name.

Example: "Austin"
address.​statestring= 2 charactersrequired

Two-letter state code (e.g., "TX").

Example: "TX"
address.​postal_codestringrequired

ZIP or postal code.

Example: "78745"
address.​countrystringrequired

Two-letter ISO 3166-1 alpha-2 country code.

Default "US"
Example: "US"
phonestring

Store phone number in E.164 format (e.g., "+15125551234").

Example: "+15125551234"
latitudenumber or null(double)

Latitude in decimal degrees (WGS 84 datum). Null if the location has not been geocoded. Use with longitude for store locator features and distance calculations.

Example: 30.2277
longitudenumber or null(double)

Longitude in decimal degrees (WGS 84 datum). Null if the location has not been geocoded.

Example: -97.7553
timezonestringrequired

IANA timezone identifier for this location. Used to interpret business_hours and daily_sales_start_time/end_time fields.

Example: "America/Chicago"
online_ordering_enabledbooleanrequired

Whether this location currently accepts online orders. Only locations with online_ordering_enabled=true should be displayed to customers.

default_prep_time_minutesinteger or null

Default estimated preparation time in minutes for orders at this location. Used to compute estimated_ready_at on orders when no item-specific prep time applies. Null if the location has not configured a default.

Example: 15
minimum_order_amountsobject or null

Minimum order subtotal required per handoff mode. If a customer's cart subtotal is below the minimum for their selected handoff mode, the server automatically applies a SMALL_ORDER fee covering the shortfall rather than blocking the order. Null if no minimums are configured.

Keys are lowercase handoff mode identifiers. Only modes with minimums are present -- absence means no minimum for that mode.

Example: {"delivery":{"amount":1500,"currency":"USD"},"pickup":{"amount":500,"currency":"USD"}}
business_hoursArray of objects

Weekly business hours for this location. One entry per day of the week. Hours are in the location's local timezone.

Response
application/json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "QuickStop #247",
  "address": {
    "street": "4521 Congress Ave",
    "city": "Austin",
    "state": "TX",
    "postal_code": "78745",
    "country": "US"
  },
  "phone": "+15125551234",
  "timezone": "America/Chicago",
  "online_ordering_enabled": true,
  "business_hours": [
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … }
  ]
}

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