Build on Omnitopia

01Quick Start

You're sending orders into a kitchen in 5 minutes. Here's the entire flow.

Step 1 — Get an API key

Generate a sandbox API key from your developer dashboard. Sandbox keys work against the test environment and never bill real merchants. Production keys come after waitlist approval.

Step 2 — Send your first order

One curl command, one order on a real (sandbox) kitchen ticket printer:

Step 3 — Receive the webhook

Within 200ms, Omnitopia sends a webhook to your configured endpoint confirming the order was accepted, queued, and printed. You're done.

02Authentication

All API requests require a Bearer token in the Authorization header. Tokens come in two flavors:

• Sandbox keys — prefixed sk_sandbox_. Free, unlimited, never bill anyone. Use for development and testing.
• Production keys — prefixed sk_live_. Available after waitlist approval. Tied to your billing account.

Key rotation

Rotate keys at any time from the developer dashboard. Old keys remain valid for 24 hours after rotation so you can deploy the new key without downtime. Compromised keys can be revoked instantly with a single API call.

Scopes

Tokens carry scopes that limit what they can do. Sandbox keys default to all scopes; production keys default to read-only and require explicit scope grants for write operations.

03Core Concepts

Universal Menu Schema (UMS)

Every menu item across every connected platform maps to a single UMS ID. A burger that's ITEM-892 in Toast, sq_burger_v3 in Square, and doordash_burger_2024 on DoorDash all resolve to BURGER_01 in Omnitopia. You write code against the UMS ID, Omnitopia handles the platform translation.

Order Injection vs POS Sync

There are two fundamentally different patterns for working with restaurant systems:

• Order Injection (this API) — your app sends an order TO the kitchen. The order didn't originate from a customer-facing app like DoorDash; it came from your kiosk, your AI agent, your custom mobile app. Omnitopia routes it through the POS as if it were a normal order, prints kitchen tickets, fires the KDS.
• POS Sync (separate API) — Omnitopia listens to the merchant's POS for orders that came in through normal channels (DoorDash, dine-in, etc.) and pushes those events out to your app via webhook. This is read-only — your app observes, doesn't inject.

Merchant ID

Every order, webhook, and SKU operation is scoped to a single merchant. The merchantId field is required on every request. Sandbox merchants are prefixed M-TEST-; production merchants are prefixed M-PROD-.

04Order Injection

Request payload

Line item structure

Successful response

Voids and refunds

Send a POST to /v1/order/{omnitopiaOrderId}/void to void an unfulfilled order, or /v1/order/{omnitopiaOrderId}/refund with a refund amount to refund a completed order. Both operations require orders:write scope.

05SDK Samples

Same order injection in five languages. Pick your stack.

06Webhooks

Subscribe to events and receive HTTP POST notifications at your endpoint as soon as something happens. All webhooks are signed with HMAC-SHA256 — verify the signature in the X-Omnitopia-Signature header before trusting payloads.

Event types

Retry policy

Failed webhook deliveries (any non-2xx response) are retried with exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours. After 5 failures the webhook is marked failed and listed in your dashboard.

Signature verification

Verify the X-Omnitopia-Signature header matches the HMAC-SHA256 of the raw request body using your webhook signing secret:

07Hardware (CloudPRNT)

CloudPRNT is the protocol Omnitopia uses to fire kitchen tickets directly to thermal printers without going through the POS print queue. This bypasses the typical 30-90 second POS delay, putting paper in the cook's hands within ~2 seconds of order injection.

Compatible printers

• Star Micronics — TSP100, TSP650, mC-Print2, mC-Print3
• Epson — TM-T88VI, TM-m30II, TM-m50
• Citizen — CT-S310II, CT-E351 (with CloudPRNT firmware)

Setup

Plug the printer into the merchant's network. From the Omnitopia dashboard, add the printer by IP address and assign it to a merchant. Print queue routing happens automatically based on order type (kitchen tickets vs receipts vs labels).

Direct print API

If you need to fire a non-order print job (custom kitchen note, label, etc.), use the print endpoint:

08Rate Limits & Overage

Every paid tier includes a generous monthly call allowance and a steady-state per-minute throttle. If you exceed your included monthly calls, your orders keep flowing — Omnitopia automatically meters overage at the rate shown below and adds it to your next invoice. No 429 errors. No interrupted service. No emergency upgrades on a busy weekend.

The per-minute steady rate is a separate throttle to protect platform stability against runaway loops. Bursts above the steady rate are absorbed by the burst capacity. Sustained spikes that exceed both steady and burst return HTTP 429 with a Retry-After header — implement exponential backoff and you'll never hit it.

How to think about overage

Overage is designed to be a safety net, not a revenue trap. The math: if you're consistently using 20%+ over your tier's included calls, upgrading to the next tier almost always costs less than the overage. Your dashboard surfaces this calculation in real time so you'll see "you'd save $X by upgrading to Growth" before you accumulate a bill that surprises you. Most merchants never see overage charges — it exists so the few who do never face an outage.

09Error Codes

All errors return JSON with a code, message, and HTTP status.

10Sandbox & Testing

The sandbox is a complete copy of the production API with test merchants, test SKUs, and test printers. Nothing in sandbox affects real merchants or real money.

Test merchants

• M-TEST-001 — Single-location burger joint, Toast + DoorDash + UberEats
• M-TEST-002 — Full-service restaurant, all 6 platforms connected
• M-TEST-003 — Multi-location franchisee, 12 connected printers

Simulating webhook events

Use the sandbox dashboard's "Trigger event" button to fire any event type at your webhook endpoint with realistic test data. Useful for end-to-end testing without placing actual orders.

Testing edge cases

Special test merchant IDs trigger specific failure modes for resilience testing:

• M-TEST-SLOW — All requests delayed 5 seconds (test your timeout handling)
• M-TEST-FLAKY — 30% of requests fail with 500 (test your retry logic)
• M-TEST-PRINTER-OFFLINE — All print jobs return 503 (test your error handling)

11Pricing Tiers

Flat monthly subscription. No per-transaction fees. No commission. No hidden cuts.