REST API Reference

Send print jobs to your receipt printers with a simple HTTP POST. No SDK or WebSocket connection required.

Base URL: https://www.receiptkit.io

Authentication: Bearer token via Authorization header. See Authentication.

POST/api/bridge/print

Send a print job to a specific printer via Receipt Bridge. The server publishes the job to your bridge over MQTT, which renders the template and sends it to the printer. Typical end-to-end latency is under 500ms.

Performance tip: Only printerEndpoint is required — the server resolves the owning bridge automatically via a database lookup. For faster execution, include the optional bridgeId parameter to skip the DB round-trip entirely. Use GET /api/bridge/printers/lookup to resolve the bridge ID once, then cache and reuse it.

Request Headers

Header	Value
Authorization	Bearer rk_live_... or Bearer rk_pub_...
Content-Type	application/json

Request Body

Parameter	Type	Description
`printerEndpoint`*	string	Printer endpoint. TCP printers can use readable device MACs like `"tcp:00:11:62:32:5a:2a"`; ReceiptKit normalizes them internally. USB printers use `"usb:2651024031300090"`.
`bridgeId`	string	Bridge ID that owns this printer. When provided, skips the database lookup for faster execution. Use `GET /api/bridge/printers/lookup?printerEndpoint=...` to resolve a printer endpoint to its bridge ID, then cache the result.
`templateId`	string	ID of a template stored in ReceiptKit. The bridge uses its cached copy for fast rendering. Either `templateId` or `template` is required.
`template`	object	Inline template definition. Use this to send a template directly without storing it in ReceiptKit first. Either `templateId` or `template` is required.
`data`*	object	The data to merge into the template. Keys correspond to template variable placeholders (e.g., `{{storeName}}`, `{{items}}`).
`dotWidth`	number	Override the raster width in dots. Omit to use the printer's native width (recommended).
`drawer`	string	Cash drawer kick mode. Options: `"START"`, `"END"`, `"BOTH"`, `"NONE"`. Defaults to `"START"`.
`source`	string	Optional identifier for the source of the print job (e.g., `"pos"`, `"web"`). Defaults to `"api"`.

Response

200 OK

{
  "success": true,
  "jobToken": "bridge-print-1709312400000-abc123",
  "bridgeId": "bridge-abc12345",
  "printerEndpoint": "tcp:00:11:62:32:5a:2a",
  "printerMac": "00:11:62:32:5a:2a",
  "topic": "receiptkit/org/{orgId}/to-bridge/{bridgeId}/print",
  "elapsed": 45,
  "timings": {
    "auth": 12,
    "body": 1,
    "mqtt": 28,
    "total": 45
  }
}

The bridgeId in the response identifies which bridge processed the job. If you included bridgeId in the request, the DB lookup is skipped entirely.

Error Responses

Status	Description
422	Missing or invalid required field (printerEndpoint, templateId/template, or data)
401	Invalid or missing API key
404	No printer found with that endpoint in this organization
409	Multiple bridges found for the same printer endpoint (ambiguous — remove the duplicate)
500	Internal error (MQTT publish failure, no API key found for org)

CORS

This endpoint has open CORS (Access-Control-Allow-Origin: *). You can call it directly from browser-side JavaScript with a rk_pub_ key. Security is enforced by API key validation, not origin restrictions.

Examples

async function printReceipt(data) {
  const response = await fetch("https://www.receiptkit.io/api/bridge/print", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.RECEIPTKIT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      printerEndpoint: "tcp:00:11:62:32:5a:2a",
      templateId: "tmpl-uuid-here",
      data,
      // Optional: bridgeId: "bridge-abc12345",
    }),
  });

  const result = await response.json();
  if (!response.ok) throw new Error(result.error || "Print failed");
  return result;
}

GET/api/bridge/printers/lookup

Resolve a printer endpoint to its bridge ID and basic metadata. Cache the bridgeId and pass it to POST /api/bridge/print to skip the per-request database lookup — faster and cheaper.

Query Parameters

Parameter	Type	Description
`printerEndpoint`*	string	Printer endpoint to look up, such as `tcp:00:11:62:32:5a:2a` or `usb:2651024031300090`.

Response

200 OK

{
  "printerEndpoint": "tcp:00:11:62:32:5a:2a",
  "bridgeId": "bridge-2ddf41d9",
  "name": "Star mC-Print3",
  "model": "Star mC-Print3",
  "ip": "192.168.4.183",
  "port": 9100
}

Usage Pattern

JavaScript

// 1. Resolve bridgeId once and cache it
const lookup = await fetch(
  "https://www.receiptkit.io/api/bridge/printers/lookup?printerEndpoint=tcp:00:11:62:32:5a:2a",
  { headers: { Authorization: `Bearer ${apiKey}` } }
).then(r => r.json());

const bridgeId = lookup.bridgeId; // cache this!

// 2. Use cached bridgeId in print calls (skips DB lookup)
await fetch("https://www.receiptkit.io/api/bridge/print", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    printerEndpoint: "tcp:00:11:62:32:5a:2a",
    bridgeId,  // <-- skips DB lookup
    templateId: "tmpl-uuid-here",
    data: { storeName: "Acme", total: "$20.49" },
  }),
});

Error Responses

Status	Description
400	Missing `printerEndpoint` query parameter
401	Invalid or missing API key
404	No printer found with that endpoint in this organization

Other Endpoints

GET/api/bridge/releases/latest

Returns the latest Receipt Bridge version and download URL. No authentication required.

GET/api/bridge/releases/check

Returns a Tauri-compatible update manifest for the Receipt Bridge auto-updater. Used internally by the bridge to check for updates.

POST/api/bridge/validate

Validates a secret API key and returns the associated organization identity. Used by Receipt Bridge during initial setup. Requires rk_live_ key.

Need Real-Time Communication?

The REST API is the simplest way to send print jobs. For real-time features like printer status monitoring, bridge discovery, and live connection state, use the receiptkit JavaScript SDK.