REST API Reference

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

Base URL: https://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 printerMac 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

HeaderValue
AuthorizationBearer rk_live_... or Bearer rk_pub_...
Content-Typeapplication/json

Request Body

ParameterTypeDescription
printerMac*stringMAC address of the target printer (e.g., "00:11:62:32:5A:2A"). Colons and hyphens are normalized automatically.
bridgeIdstringBridge ID that owns this printer. When provided, skips the database lookup for faster execution. Use GET /api/bridge/printers/lookup?mac=... to resolve a printer MAC to its bridge ID, then cache the result.
templateIdstringID of a template stored in ReceiptKit. The bridge uses its cached copy for fast rendering. Either templateId or template is required.
templateobjectInline template definition. Use this to send a template directly without storing it in ReceiptKit first. Either templateId or template is required.
data*objectThe data to merge into the template. Keys correspond to template variable placeholders (e.g., {{storeName}}, {{items}}).
dotWidthnumberOverride the raster width in dots. Omit to use the printer's native width (recommended).
drawerstringCash drawer kick mode. Options: "START", "END", "BOTH", "NONE". Defaults to "START".
sourcestringOptional 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",
  "printerMac": "001162325a2a",
  "topic": "receiptkit/org/{orgId}/001162325a2a/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

StatusDescription
400Missing required field (printerMac, templateId/template, or data)
401Invalid or missing API key
403API key revoked or insufficient permissions
404No printer found with that MAC address in this organization
409Multiple bridges found for the same printer MAC (ambiguous — remove the duplicate)
500Internal 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

curl

Shell
curl -X POST https://receiptkit.io/api/bridge/print \
  -H "Authorization: Bearer rk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "printerMac": "00:11:62:32:5A:2A",
    "templateId": "tmpl-uuid-here",
    "data": {
      "storeName": "Acme Hardware",
      "address": "123 Main St",
      "items": [
        { "name": "Hammer", "qty": 1, "price": "$12.99" },
        { "name": "Nails (box)", "qty": 2, "price": "$5.98" }
      ],
      "subtotal": "$18.97",
      "tax": "$1.52",
      "total": "$20.49",
      "paymentMethod": "Visa *4242"
    }
  }'

Node.js

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

  const result = await response.json();
  if (!response.ok) {
    throw new Error(result.error);
  }
  return result; // { success: true, jobToken: "...", elapsed: 45 }
}

Python

Python
import requests
import os

def print_receipt(data: dict) -> dict:
    response = requests.post(
        "https://receiptkit.io/api/bridge/print",
        headers={
            "Authorization": f"Bearer {os.environ['RECEIPTKIT_API_KEY']}",
            "Content-Type": "application/json",
        },
        json={
            "printerMac": "00:11:62:32:5A:2A",
            "templateId": "tmpl-uuid-here",
            "data": data,
        },
    )
    response.raise_for_status()
    return response.json()  # {"success": True, "jobToken": "...", "elapsed": 45}
GET/api/bridge/printers/lookup

Resolve a printer MAC address 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

ParameterTypeDescription
mac*stringMAC address of the printer to look up. Colons and hyphens are normalized.

Response

200 OK
{
  "printerMac": "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://receiptkit.io/api/bridge/printers/lookup?mac=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://receiptkit.io/api/bridge/print", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    printerMac: "00:11:62:32:5a:2a",
    bridgeId,  // <-- skips DB lookup
    templateId: "tmpl-uuid-here",
    data: { storeName: "Acme", total: "$20.49" },
  }),
});

Error Responses

StatusDescription
400Missing mac query parameter
401Invalid or missing API key
404No printer found with that MAC address 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 an API key and returns the associated organization ID, bridge configuration, and MQTT connection details. 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/mqtt-client library.