Receiptful API

Version 1.1.0

Receiptful lets you print receipts on thermal printers from anywhere via a simple REST API.

Getting Started

How It Works

You send print jobs to our API
We push them to your Android devices running our app
The app prints to thermal printers connected via Bluetooth or USB

No printer drivers, no infrastructure headaches. Just an API call and your receipt prints.

Quick Start

# 1. Get your API key
curl -X POST /v1/users \
  -H "Content-Type: application/json" \
  -d '{"email": "your@email"}'

# 2. Register a printer (gives you a 6-character login code)
curl -X POST /v1/printers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Kitchen"}'

# 3. Install the Android app and enter the login code (valid 7 days)
#    Download: https://receiptful.io/files/android_v1.apk

# 4. Print an HTML receipt
curl -X POST /v1/printers/1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: text/html" \
  -d '<h3>Hello World</h3><p>Your receipt here</p><cut/>'

Authentication

Every request needs an Authorization: Bearer YOUR_API_KEY header. Get your key

from POST /v1/users — it's returned once, so save it. Missing, malformed, or

unknown keys return 401 Unauthorized. Treat your key as a secret — it scopes

all printers and print jobs to your account.

Users

Create a user account to get your API key. One user = one API key = isolated printers and jobs.

Create User

POST /v1/users

Create a new user account and get your API key.

The returned api_key is the plaintext value of the first project API

key. It is shown once; subsequent reads only expose last4.

Printers

Create Printer

POST /v1/printers

Returns a login_code that you enter in our Android app to log the printer in.

Once logged in, you can send print jobs to it.

Parameters: authorization

List Printers

GET /v1/printers

List all your printers.

Shows login status (is_logged_in) and pending login codes for printers that

aren't logged in yet.

Parameters: authorization

Get Printer

GET /v1/printers/{printer_id}

Get a specific printer's details.

Parameters: printer_id, authorization

Update Printer

PATCH /v1/printers/{printer_id}

Update a printer's label or profile.

Parameters: printer_id, authorization

Delete Printer

DELETE /v1/printers/{printer_id}

Delete a printer.

The printer is soft-deleted and print job history is preserved.

The Android app will be logged out.

Parameters: printer_id, authorization

Refresh Login Code

POST /v1/printers/{printer_id}/refresh-login-code

Generate a new login code.

Use this if the previous code expired or you need to log in a different device.

Parameters: printer_id, authorization

List Printer Profiles

GET /v1/printer-profiles

The known python-escpos printer profiles, for the console's profile

dropdown. Project-scoped auth keeps the override path uniform with the

rest of /v1; the catalog itself is project-independent.

Parameters: authorization

Print Jobs

Send print jobs by POSTing HTML (Content-Type: text/html) or raw ESC/POS bytes (Content-Type: application/vnd.escpos) directly to your printer. Track job status via polling.

Create Print Job

POST /v1/printers/{printer_id}/jobs

Send a print job to a printer.

Set Content-Type to match the body:

text/html - HTML rendered server-side to ESC/POS using the printer's profile.
application/vnd.escpos - raw ESC/POS bytes stored verbatim.
application/json - render a stored receipt template: reference it via

template_id or template_name (id wins if both are sent) and supply the

template's variables in data. Rendering is strict — a variable the

template uses but data omits rejects the job with a 422.

Raw bodies are capped at 1 MB. The job expires after the optional

X-Lifetime-Seconds header or lifetime_seconds query parameter

(default: 600 = 10 minutes).

If the printer doesn't pick it up in time, it won't print.

Parameters: printer_id, lifetime_seconds, X-Lifetime-Seconds, authorization

List Print Jobs

GET /v1/printers/{printer_id}/jobs

List print jobs for a printer.

Returns jobs in reverse chronological order (newest first).

Parameters: printer_id, limit, offset, authorization

Get Print Job

GET /v1/printers/{printer_id}/jobs/{job_id}

Get a print job's status.

Tracking Status

A print job moves through this status sequence:

created → notification_sent → notification_received → printing → completed

Poll this endpoint to track its current status.

The response includes the full history in status_history (chronological), and the

submitted html (null for raw ESC/POS jobs).

Parameters: printer_id, job_id, authorization

Redact Print Job

POST /v1/printers/{printer_id}/jobs/{job_id}/redact

Irreversibly erase a print job's content (GDPR erasure).

Empties the stored ESC/POS bytes and removes the source HTML and

template data, keeping the job itself and its status history as

anonymous metadata. Sets redacted_at; a redacted job can no longer

be printed. Idempotent — redacting an already redacted job returns

200 and keeps the original redacted_at.

Parameters: printer_id, job_id, authorization

Endpoints

Health Check

GET /health