Skip to content
API Reference
/
/
Refund an order (full or...

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

Submit a payment for an order

Request

Attaches a payment to an order. Supports credit cards, debit cards, gift cards, loyalty points, and digital wallets.

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 re-processing the payment. Error responses are NOT cached.

Split payments: To pay with multiple tenders, submit separate payment requests for each tender. Each request must use a different Idempotency-Key.

Ordering rules: Submit tenders in this order: loyalty points first, then gift cards, then credit/debit cards. This maximizes non-cash tender redemption.

Sequential submission: Wait for each payment to reach a terminal state (COMPLETED or FAILED) before submitting the next. Concurrent submissions on the same order may produce undefined behavior.

Failure handling for split payments: If a payment fails mid-sequence, previous successful payments remain. You must either: (a) retry the failed tender with the same Idempotency-Key, (b) submit a different tender for the remaining balance, or (c) cancel the order (which triggers void/refund of all successful payments).

Security
oauth2
Path
order_idstring(uuid)required

Unique identifier for the order.

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
payment_methodstring(PaymentMethod)required

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_tenders on 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"
amountobject(Money)required

Amount to charge for this tender. For a single payment, this equals the order total. For split payments, this is the portion covered by this tender. The sum of all successful payment amounts must equal the order total.

amount.​amountintegerrequired

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

Example: 1299
amount.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
tip_amountMoney (object) or null

Optional tip amount. Typically included on the final tender in a split payment sequence. Null or omit if no tip.

One of:

Optional tip amount. Typically included on the final tender in a split payment sequence. Null or omit if no tip.

payment_detailsobject or null

Method-specific payment details. Required fields vary by payment_method:

CREDIT_CARD / DEBIT_CARD:

{ "token": "tok_visa_4242" }

Use a tokenized card reference from your payment form. Never send raw card numbers through this API.

GIFT_CARD:

{ "card_number": "6789012345678901", "pin": "1234" }

LOYALTY_POINTS:

{ "loyalty_account_id": "LOY-123456" }

DIGITAL_WALLET:

{ "wallet_token": "dw_applepay_abc123", "wallet_type": "apple_pay" }
curl -i -X POST \
  'https://developers.tote.ai/_mock/online-ordering/spec/openapi/orders/{order_id}/payments' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: d7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23' \
  -d '{
    "payment_method": "CREDIT_CARD",
    "amount": {
      "amount": 1945,
      "currency": "USD"
    },
    "tip_amount": {
      "amount": 200,
      "currency": "USD"
    },
    "payment_details": {
      "token": "tok_visa_4242"
    }
  }'

Responses

Payment accepted and processing complete. The payment has been attached to the order.

Bodyapplication/json
idstring(uuid)required

Unique identifier for the payment.

order_idstring(uuid)required

The order this payment is attached to.

statusstring(PaymentStatus)required

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"
payment_methodstring(PaymentMethod)required

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_tenders on 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"
amountobject(Money)required

The payment amount in cents.

amount.​amountintegerrequired

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

Example: 1299
amount.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
tip_amountMoney (object) or null

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.

payment_detailsobject or null

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" }
idempotency_keystring(uuid)

The idempotency key used when this payment was submitted.

created_atstring(date-time)required

When the payment was created.

updated_atstring(date-time)required

When the payment status was last updated.

Response
application/json
{
  "id": "a1b2c3d4-0001-4000-8000-000000000001",
  "order_id": "f9a8b7c6-d5e4-3210-fedc-ba9876543210",
  "status": "COMPLETED",
  "payment_method": "CREDIT_CARD",
  "amount": {
    "amount": 1945,
    "currency": "USD"
  },
  "tip_amount": {
    "amount": 200,
    "currency": "USD"
  },
  "payment_details": {
    "last_four": "4242",
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2027
  },
  "idempotency_key": "d7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23",
  "created_at": "2026-01-31T10:08:00Z",
  "updated_at": "2026-01-31T10:08:02Z"
}

Refund an order (full or partial)

Request

Processes a full or partial refund for an order. The server determines how to distribute the refund across the order's payment methods using a minimize-cash-refund strategy (non-cash tenders are refunded first).

Full refund: Set amount to the order's total paid amount. Partial refund: Set amount to the desired refund amount. Item-level refund: Include line_items to record which items are being refunded (informational -- the amount field determines the refund total).

The refund amount must not exceed the order's refundable balance (amount_paid - amount_refunded). Multiple partial refunds can be issued until the full amount has been refunded.

Security
oauth2
Path
order_idstring(uuid)required

Unique identifier for the order.

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
amountobject(Money)required

Refund amount in cents. For a full refund, set this to the order's total paid amount. For a partial refund, set this to the desired refund amount.

amount.​amountintegerrequired

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

Example: 1299
amount.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
reasonstringrequired

Reason for the refund. This is stored for record-keeping and may be visible to the customer.

Enum"CUSTOMER_REQUEST""ITEM_UNAVAILABLE""INCORRECT_ORDER""QUALITY_ISSUE""DUPLICATE_CHARGE""OTHER"
reason_notestring or null<= 500 characters

Free-text note providing additional context for the refund reason. Required when reason is OTHER.

line_itemsArray of objects(RefundLineItem)

Optional item-level refund detail. When provided, specifies which items are being refunded and their quantities. This is informational for record-keeping -- the refund amount is determined by the amount field, not by summing line item prices.

curl -i -X POST \
  'https://developers.tote.ai/_mock/online-ordering/spec/openapi/orders/{order_id}/refunds' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: d7a8fbb3-07d4-4e3c-b5f2-9a6c8b1e0f23' \
  -d '{
    "amount": {
      "amount": 1945,
      "currency": "USD"
    },
    "reason": "CUSTOMER_REQUEST",
    "reason_note": null
  }'

Responses

Refund created and processing initiated. The refund_allocations array shows how the refund was distributed across payment methods.

Bodyapplication/json
idstring(uuid)required

Unique identifier for the refund.

order_idstring(uuid)required

The order this refund applies to.

statusstringrequired

Refund processing status. PENDING means the refund has been accepted and is being processed. COMPLETED means all refund allocations have been processed. FAILED means the refund could not be processed.

Enum"PENDING""COMPLETED""FAILED"
amountobject(Money)required

Total refund amount.

amount.​amountintegerrequired

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

Example: 1299
amount.​currencystring= 3 charactersrequired

ISO 4217 currency code.

Default "USD"
Example: "USD"
reasonstringrequired
Enum"CUSTOMER_REQUEST""ITEM_UNAVAILABLE""INCORRECT_ORDER""QUALITY_ISSUE""DUPLICATE_CHARGE""OTHER"
reason_notestring or null
refund_allocationsArray of objects

How the refund was distributed across original payments. The server uses a minimize-cash-refund strategy: non-cash tenders (gift cards, loyalty points) are refunded first, then card payments.

line_itemsArray of objects(RefundLineItem)

Item-level refund details, if provided in the request.

created_atstring(date-time)required

When the refund was created.

Response
application/json
{
  "id": "b1c2d3e4-0001-4000-8000-000000000001",
  "order_id": "f9a8b7c6-d5e4-3210-fedc-ba9876543210",
  "status": "COMPLETED",
  "amount": {
    "amount": 1945,
    "currency": "USD"
  },
  "reason": "CUSTOMER_REQUEST",
  "reason_note": null,
  "refund_allocations": [
    { … },
    { … },
    { … }
  ],
  "line_items": [],
  "created_at": "2026-01-31T11:00:00Z"
}

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