Skip to content
PenBlitz
← Developers

API: orders for shops

One call per customer: text, recipient, done. Made for shops and CRM systems.

Place an order

An order is a handwritten piece for one recipient. PenBlitz picks the template of the product, fills in text and address and queues the job.

FieldMeaning
productpostcard, letter or card. GET /api/v1/products lists them.
textThe text to write. May contain placeholders filled from variables.
recipientname, street, postal_code, city, country.
external_idYour own order number.
with_envelopeAlso write a DL envelope with the address.
qr_dataAdds a QR code below the text.
template_idUse this template instead of the one of the product.
scheduled_atDo not start before this time.
callback_urlAddress that is notified when the order is done.
curl -X POST http://127.0.0.1:8787/api/v1/orders \
  -H 'Content-Type: application/json' \
  -d '{
    "external_id": "A-1042",
    "product": "postcard",
    "text": "Dear {first_name}, happy birthday!",
    "variables": {"first_name": "Jane"},
    "recipient": {"name": "Jane Doe", "street": "1 Main St", "postal_code": "12345", "city": "Springfield"},
    "with_envelope": false
  }'

No double prints

Send the same external_id again and you get the existing order back instead of a second print. It is safe to repeat a call after a timeout.

Status

GET /api/v1/orders/{id} accepts the order id or your external_id.

StatusMeaning
pendingScheduled for later.
queuedWaiting or being written.
sentWritten.
failedCould not be written.
canceledCanceled.

Cancel

DELETE /api/v1/orders/{id} cancels an order that has not been written yet.

Change the layout

The products point to the templates postcard, letter and card. Load the template in the app, adjust it and save it under the same id; every later order uses the new layout.