Toster API

Overview

All API endpoints are REST and return JSON. Authentication uses a Bearer token sent in the Authorization header. Each API key carries a set of scopes that controls exactly which endpoints it can reach.

Authentication

Generate an API key in Settings → API Keys inside your Toster dashboard. Keys look like 966_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

Pass the key as a Bearer token on every request:

curl https://api.toster.co/api/orders \
  -H "Authorization: Bearer 966_YOUR_API_KEY" \
  -H "Accept: application/json"

const res = await fetch('https://api.toster.co/api/orders', {
  headers: {
    Authorization: 'Bearer 966_YOUR_API_KEY',
    Accept: 'application/json',
  },
});
const { items, total } = await res.json();

Scopes

Each key is issued with a set of scopes. Calling an endpoint without the required scope returns 403 Forbidden.

Pagination & Errors

List endpoints support ?page=1&limit=20 (max 100). The response envelope is always:

{
  "items": [...],
  "total": 1842,
  "page": 1,
  "pages": 93
}

Errors follow a consistent shape:

{
  "error": "Order not found",
  "details": { "id": "ord_abc123" }
}

Create, read, and manage the full order lifecycle from placement to delivery.

Access and manage customer profiles, tags, segments, and purchase history.

Read your full menu catalogue including categories, modifiers, and pricing.

Monitor the live kitchen queue and cooking status for each station.

Track courier locations, assignments, and shift performance in real time.

Pull revenue, order volume, and funnel data for any date range.

Read and manage loyalty balances, award bonuses, and process redemptions.

Instead of polling, subscribe to events and Toster will POST a JSON payload to your URL within seconds of the event firing.

Example order.created payload:

{
  "event": "order.created",
  "created_at": "2026-04-28T14:22:00Z",
  "data": {
    "id": "clx7...",
    "number": 4821,
    "status": "NEW",
    "total": 1250,
    "customer": {
      "id": "clx8...",
      "name": "Anna K.",
      "phone": "+380671234567"
    },
    "items": [
      { "name": "Philadelphia Roll", "qty": 2, "price": 340 }
    ]
  }
}

Verify the request is from Toster using the X-Toster-Signature header — an HMAC-SHA256 of the raw body signed with your webhook secret.

import { createHmac } from 'crypto';

function verifySignature(rawBody, signature, secret) {
  const expected = createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return `sha256=${expected}` === signature;
}