Cloud printing
Print from your server, with no browser open, through our API.
Your server sends a print job to Taprel’s API, and the Taprel app prints it on the computer you choose. No browser needs to be open, so an online order that arrives at 2 am still prints in the kitchen.
How it works
- Your server sends a cloud job to
https://api.taprel.com, naming a computer and a printer. - We keep it until the Taprel app on that computer fetches it. A computer that’s off gets it when it’s back, within the time the job may wait.
- The app prints it and reports the result, which your server can read.
The app connects out to us, so nothing is opened on the shop’s network. Cloud printing is on Pro, and on the trial for up to 100 cloud jobs. To print from a page open on the same PC, the Quick start is simpler and needs no server.
1Link the computer
Cloud jobs only go to a computer linked to your account:
- In the Taprel app, open Settings, go to Taprel account and click Show code.
- Type the code on your account’s Computers page. It lasts 15 minutes.
Cloud printing is then on. Someone at the computer can turn it off in the app’s Settings. A computer linked by an older app needs the app updated and the computer linked again.
2Make an API key
On your account’s API keys page, click Create key and give it a name, like “Production server”. The key is shown once, starting with tp_live_, with a command that prints a test receipt.
Keep it on your server, never in a web page or an app: anyone with it can print on your computers. A key you revoke stops working at once, and the jobs it already sent still print.
3Send a job
In a Linux or Mac terminal, with your key in TAPREL_API_KEY:
curl https://api.taprel.com/v1/jobs \
-H "Authorization: Bearer $TAPREL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"computer": "Kitchen PC", "printer": "receipt",
"document": {"version": 1, "type": "receipt", "content": [
{"text": "Order 1042", "align": "center", "bold": true, "size": 2},
{"row": ["2 x Margherita", "19.00"]},
{"cut": true}]}}'
document is the same JSON as a print from the browser. The answer, 202, has the job’s ID:
{
"id": "job_01JC8Y3M6V0K9T4Q2W7XHZBN5R",
"status": "queued",
"createdAt": "2026-11-10T14:03:00Z",
"expiresAt": "2026-11-10T15:03:00Z",
"computer": { "id": "cmp_01JC7RG2SM4D6YB8K0TQX3NA5W", "name": "Kitchen PC", "online": true, "lastSeenAt": "2026-11-10T14:02:31Z" }
}
online is false when the app hasn’t been in touch for over two and a half minutes, so your server can warn someone that the kitchen PC is off. The job still waits for it.
From a Node server, build the document with the same receipt() and label() as in the browser:
import { receipt } from "@taprel/sdk";
const doc = receipt([
{ text: `Order ${order.id}`, align: "center", bold: true, size: 2 },
...order.items.map((item) => ({ row: [`${item.qty} x ${item.name}`, item.price.toFixed(2)] })),
{ row: ["Total", order.total.toFixed(2)], bold: true },
{ cut: true },
]);
const response = await fetch("https://api.taprel.com/v1/jobs", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TAPREL_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": `order-${order.id}`,
},
body: JSON.stringify({ computer: "Kitchen PC", printer: "receipt", document: doc }),
});
const job = await response.json();
Any language that sends HTTPS works the same way. Idempotency-Key makes a retry safe, see Send a job only once.
Choose the computer and printer
computeris its name, exactly as on the Computers page, or itsid, likecmp_01JC7RG2SM4D6YB8K0TQX3NA5W. If two computers share a name, use theid.GET /v1/computerslists both.printerisreceipt,labelorregular, the printer set as that type in the app on that computer, so the same code works in every shop. Or an exact printer name, when you need one printer in particular.
Follow a job
curl https://api.taprel.com/v1/jobs/job_01JC8Y3M6V0K9T4Q2W7XHZBN5R \
-H "Authorization: Bearer $TAPREL_API_KEY"
The answer says where it is and what happened, never what it printed:
{
"id": "job_01JC8Y3M6V0K9T4Q2W7XHZBN5R",
"status": "printed",
"computer": { "id": "cmp_01JC7RG2SM4D6YB8K0TQX3NA5W", "name": "Kitchen PC" },
"printer": "receipt",
"content": "document",
"bytes": 214,
"createdAt": "2026-11-10T14:03:00Z",
"sentAt": "2026-11-10T14:03:01Z",
"finishedAt": "2026-11-10T14:03:02Z",
"expiresAt": "2026-11-10T15:03:00Z",
"sends": 1,
"error": null,
"warnings": []
}
| Status | Meaning |
|---|---|
queued |
Waiting for the computer to fetch it |
sent |
The app has it, with no result yet |
printed |
The app handed it to Windows’ print queue. Like a print from the browser, this doesn’t prove paper came out: a printer out of paper still takes the job |
failed |
It didn’t print. error has a code and a message |
expired |
The computer didn’t fetch it in time |
cancelled |
You cancelled it before it was sent |
The last four are final. warnings lists what couldn’t be done on a printed job, like cutting on a printer that can’t cut. Any key on your account can read any of its jobs, for 30 days after it ends.
To cancel a job that hasn’t been sent yet:
curl -X DELETE https://api.taprel.com/v1/jobs/job_01JC8Y3M6V0K9T4Q2W7XHZBN5R \
-H "Authorization: Bearer $TAPREL_API_KEY"
Once the app has it, a job can’t be cancelled, because it may already have printed.
Errors
A refused request has an HTTP status, a code your code can check and an English message for your logs:
{ "error": { "code": "COMPUTER_NOT_READY", "message": "Cloud printing is turned off in the Taprel app on this computer. Turn it on in the app's Settings." } }
| HTTP | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED |
No key, or a key that’s wrong or revoked |
| 403 | PLAN_REQUIRED |
The account isn’t on Pro or its trial. After a failed payment, cloud printing keeps working through the 14 days of warnings |
| 403 | TRIAL_LIMIT |
The trial’s 100 cloud jobs are used, or this computer already had cloud jobs on another account’s trial |
| 403 | MONTHLY_LIMIT |
This month’s 10,000 cloud jobs are used |
| 404 | COMPUTER_NOT_FOUND |
No computer on the account has that name or ID |
| 404 | JOB_NOT_FOUND |
No job with that ID on the account, or it ended over 30 days ago |
| 409 | COMPUTER_AMBIGUOUS |
Several computers have that name. Use its id |
| 409 | COMPUTER_NOT_READY |
The computer isn’t linked, was linked by an app too old for cloud printing, or has cloud printing turned off. The message says which |
| 409 | JOB_NOT_CANCELLABLE |
The job was already sent, or has ended |
| 413 | TOO_LARGE |
The request is over 10 MB |
| 422 | BAD_REQUEST |
Something in the body is wrong. fields gives each mistake’s place, like document.content[3].align |
| 422 | IDEMPOTENCY_CONFLICT |
The Idempotency-Key was used in the last 24 hours for a different job |
| 429 | RATE_LIMITED |
Over 120 requests a minute for this key. Retry-After says how many seconds to wait |
A job can also end as failed after it was accepted, with the app’s own error codes, like PRINTER_NOT_FOUND, or one of ours:
COMPUTER_NOT_FOUND: the computer was removed from the account while the job waited.COMPUTER_NOT_READY: cloud printing was turned off in the app, or the computer was linked again by an older app, while the job waited.PLAN_REQUIRED: the plan ended while the job waited.DELIVERY_FAILED: the app got the job 5 times and never reported a result.
More
Send a job only once
If your request times out, you can’t tell whether the job was made. Send an Idempotency-Key header with something unique to the print, like order-1042, up to 255 characters, and send the same request again:
- The same key with the same body, within 24 hours, answers the first job again, with the header
Idempotent-Replayed: true. No second job is made. - The same key with a different body gives
IDEMPOTENCY_CONFLICT.
Keys belong to your account, not to one API key. The app never prints the same job twice either, even if it gets it again after a lost connection.
PDFs and raw bytes
Send a PDF file or bytes in the printer’s own language in base64, instead of document:
{ "computer": "Office PC", "printer": "regular", "pdf": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK", "options": { "copies": 2, "scale": "fit" } }
{ "computer": "Kitchen PC", "printer": "receipt", "raw": "G0BIZWxsbyBraXRjaGVuCh1WAA==" }
A job has exactly one of document, pdf and raw. options takes copies for a document, the PDF options for a PDF, and nothing for raw bytes. In a document, a picture is a base64 PNG or JPEG.
Your computers and their printers
curl https://api.taprel.com/v1/computers \
-H "Authorization: Bearer $TAPREL_API_KEY"
{
"computers": [
{
"id": "cmp_01JC7RG2SM4D6YB8K0TQX3NA5W",
"name": "Kitchen PC",
"cloud": "ready",
"online": true,
"lastSeenAt": "2026-11-10T14:02:31Z",
"appVersion": "0.3.0",
"printersReportedAt": "2026-11-10T13:55:12Z",
"printers": [{ "name": "Kitchen receipt", "kind": "receipt", "mainOfKind": true, "status": "ready" }]
}
]
}
cloud is ready, or why the computer can’t take jobs: not_linked, needs_relink (linked by an older app: update it and link again) or turned_off. printers are the ones the app last reported, which can be out of date: a printer name that’s gone fails on the PC with PRINTER_NOT_FOUND.
How long a job waits
A job waits 1 hour for its computer, then ends as expired. Set expiresIn in seconds, from 60 to 259200 (72 hours), for a ticket that’s no use later or an order that can wait for the morning:
{ "computer": "Kitchen PC", "printer": "receipt", "document": { "version": 1, "type": "receipt", "content": [{ "text": "Table 7" }] }, "expiresIn": 600 }
The app checks for jobs every minute while it runs, and gets a new one within seconds. A job whose result was lost, like when the computer restarts while printing, is sent again after 5 minutes.
Limits
- Pro: 10,000 cloud jobs a calendar month, counted in UTC. We email you at 80% and at 100%. Need more? Email us.
- Trial: 100 cloud jobs in all. A computer gets trial cloud jobs from only one account.
- Every accepted job counts, even if it’s cancelled or expires. A refused one doesn’t.
- 120 requests a minute per key, 10 MB per request, 10 keys per account.
What we keep
- What you print is kept encrypted until the job ends, then deleted at once. It’s never written to our logs, error reports or emails.
- The job’s details: its status, computer, printer, kind of content, size, times, sends, error and warnings, for 30 days after it ends.
- An
Idempotency-Keyfor 24 hours, with a fingerprint of the body, never the body. - Your API keys: their name, their first 12 characters and when they were made and last used. Not the key itself, so a lost key can’t be shown again: make a new one.
See the Privacy page for the rest.