POST /v1/render
Render a document from a template and data. Returns either a download URL or the rendered output inline. Send a list in data to render a batch: one label per item, in one request.
Endpoint:
POST /v1/renderRequest Body
Section titled “Request Body”You can render either a saved template (by ID) or an inline template (passed directly in the request).
Option A — Saved template:
{ "templateId": "your-template-id", "data": { "orderNumber": "ORD-9876", "customer": "Acme Corp" }, "format": "pdf"}Option B — Inline template:
{ "template": { "version": 2, "units": "in", "meta": { "name": "Badge" }, "size": { "width": 76.2, "height": 50.8 }, "elements": [ { "id": "name", "kind": "text", "position": { "x": 8, "y": 15 }, "size": { "width": 60, "height": 12 }, "expression": "attendeeName", "font": { "family": "Arial", "size": 14 }, "color": "#111111" } ] }, "data": { "attendeeName": "Jane Smith" }, "format": "png"}Fields
Section titled “Fields”| Field | Type | Required | Description |
|---|---|---|---|
templateId |
string |
One of templateId or template is required |
ID of a published template. Accepts a template ID, a team slug (e.g., shipping-label), or a library-qualified slug (e.g., carbon:product-2x1). See Template Libraries. |
template |
object |
One of templateId or template is required |
Inline template object. See Templates for the full schema. |
data |
object or array |
Yes | Data to bind into the template. An object fills one label (or, on sheet media without slots, is replicated across every cell on the page). An array of objects means one label per item. On a single-label template it is a batch: one PDF page, PNG image, ZPL block or HTML document per item. On a sheet template it tiles one item per label cell in reading order across the sheet, continuing onto more pages when the list is longer than one sheet. Top-level keys become variables in element expression and visibleExpression fields. |
format |
string |
Yes | Output format: "pdf", "png", "zpl", or "html". |
dpi |
number |
No | Resolution for raster output, from 50 to 600. Default: 300 for PNG, 203 for ZPL. Ignored for PDF and HTML, but still checked against the range. See Limits. |
delivery |
string |
No | "url" (default) returns a JSON response with a download URL. "inline" returns the rendered output directly as the response body. |
slots |
number[] |
No | Optional 1-based sheet positions for partial-sheet printing. Only valid with sheet media templates and formats html, pdf, or png. See Partial-sheet slots below. |
Partial-sheet slots
Section titled “Partial-sheet slots”When a template has sheet media (an N-up grid such as Avery 2×4), each cell on the page is a numbered slot. Numbering is 1-based and row-major from the top-left:
- Slot
1is the top-left cell. - On a 2-column grid, slot
2is the top-right cell; slot3is the second row, left cell; and so on through the bottom-right cell. - Capacity is
columns × rows(for example, 8 on a 2×4 sheet).
Pass slots to print only into chosen positions. Unselected cells render truly blank (no label content). A slots request is always a single page: you cannot request more positions than capacity.
Validation rules
Section titled “Validation rules”All of the following return HTTP 400 with code INVALID_SLOTS and a specific message:
| Rule | Detail |
|---|---|
| Sheet media required | The resolved template must have media.type === "sheet". |
| Format | Only "html", "pdf", and "png". Rejected for "zpl" (single-label path). |
| Values | Integers only, unique, each in 1..capacity. |
Array data |
slots.length must equal data.length, and both must be ≤ capacity. A full-capacity permutation is legal. |
Object data |
1 ≤ slots.length ≤ capacity. The same object is replicated into every listed slot. |
| Omitted | If slots is omitted, behaviour is unchanged from today (full-sheet fill / multi-page tiling). |
Example — array data into chosen slots
Section titled “Example — array data into chosen slots”Two data rows placed in physical positions 4 and 6 (leaving the rest blank):
{ "templateId": "avery-22890-labels", "data": [ { "name": "A" }, { "name": "B" } ], "slots": [4, 6], "format": "pdf"}Row data[i] is printed into slots[i]. Order in the array is meaningful — you may permute slots deliberately.
Example — single object into selected slots
Section titled “Example — single object into selected slots”One object copied into slots 1, 3, and 5 only:
{ "templateId": "avery-22890-labels", "data": { "name": "Jane Smith", "role": "Guest" }, "slots": [1, 3, 5], "format": "pdf"}Without slots, the same object is still replicated across every cell on the sheet (existing behaviour).
Batch: a list of labels
Section titled “Batch: a list of labels”On a single-label template (one without sheet media), a list in data renders one label per item, in input order, in one request. Each label counts as one render.
{ "templateId": "shipping-label", "data": [ { "orderNumber": "ORD-1001", "customer": "Acme Corp" }, { "orderNumber": "ORD-1002", "customer": "Globex" }, { "orderNumber": "ORD-1003", "customer": "Initech" } ], "format": "zpl"}| Format | What a list of N items returns |
|---|---|
pdf |
One document with N pages, one label per page. |
png |
N images, one per item. |
zpl |
N label blocks, one per item, plus one stream of all of them joined in order. |
html |
N documents, one per item. |
Each item is rendered exactly as if it had been sent alone: one item’s expressions cannot see another’s data.
Sheet templates are not batches. On a template with sheet media, a list fills the sheet’s cells (see data above and Partial-sheet slots) and counts as one render, as before.
List size by plan
Section titled “List size by plan”| Plan | PDF, HTML | ZPL, PNG |
|---|---|---|
| Dev | 10 | 10 |
| Small | 100 | 100 |
| Big, Enterprise | 250 | 100 |
A batch has 60 seconds to finish (a single render has 30). Send longer lists as several requests.
Batch response — URL delivery (default)
Section titled “Batch response — URL delivery (default)”Status: 200 OK
{ "batchId": "5d0c7f4e-3b1a-4c6e-9a2f-1e8b7d6c5a40", "status": "complete", "format": "zpl", "count": 3, "renderTimeMs": 1840, "warnings": [], "url": "https://api.binderypress.dev/v1/render-outputs/5d0c7f4e-3b1a-4c6e-9a2f-1e8b7d6c5a40", "sizeBytes": 135000, "items": [ { "index": 0, "id": "a1b2c3d4-…", "url": "https://api.binderypress.dev/v1/render-outputs/a1b2c3d4-…", "sizeBytes": 45000 }, { "index": 1, "id": "b2c3d4e5-…", "url": "https://api.binderypress.dev/v1/render-outputs/b2c3d4e5-…", "sizeBytes": 45000 }, { "index": 2, "id": "c3d4e5f6-…", "url": "https://api.binderypress.dev/v1/render-outputs/c3d4e5f6-…", "sizeBytes": 45000 } ]}| Field | Type | Description |
|---|---|---|
batchId |
string |
ID of the batch (UUID). |
status |
string |
"complete". |
format |
string |
The output format. |
count |
number |
Number of labels rendered: the length of data. |
renderTimeMs |
number |
Time spent rendering the whole batch, in milliseconds. |
warnings |
array |
Expressions that failed, see Warnings. Empty when every label is complete. |
url |
string |
pdf: the document. zpl: every label block joined in input order. Not present for png and html. Valid for 7 days. |
sizeBytes |
number |
Size of what url downloads. Not present for png and html. |
items |
array |
png, zpl and html: one entry per item, in input order, with its index (0-based position in data), id (its render job ID), url (download, valid for 7 days) and sizeBytes. Not present for pdf. |
Every item is its own render job in your render history, under the one batch. For pdf, each of those jobs downloads the batch’s one document.
Batch response — inline delivery
Section titled “Batch response — inline delivery”With "delivery": "inline":
pdfreturns the document itself as the body,Content-Type: application/pdf, as a single render does. TheX-Batch-Idheader carries the batch ID andX-Render-Warningsthe number of warnings; use URL delivery to see the warnings themselves.zplandhtmlreturn the JSON above, without the URLs: each entry initemshasindex,id,sizeBytesandtext, the label’s ZPL or HTML. Forzpl,joinedholds every block joined in input order. Inline results are not kept, so they have no download link.pngis not available inline for a list:400 INLINE_NOT_SUPPORTED.
The labels’ text may total at most 10 MB (joined repeats it and is not counted twice). A larger batch is refused with 400 INLINE_TOO_LARGE; nothing is counted. Send it with URL delivery to get a download link for each label. For a sense of scale, a 4 × 6 in label at 203 DPI is about 45 KB of ZPL, so 100 of them come to about 4.5 MB.
{ "batchId": "5d0c7f4e-3b1a-4c6e-9a2f-1e8b7d6c5a40", "status": "complete", "format": "zpl", "count": 2, "renderTimeMs": 1210, "warnings": [], "items": [ { "index": 0, "id": "a1b2c3d4-…", "sizeBytes": 45000, "text": "^XA…^XZ" }, { "index": 1, "id": "b2c3d4e5-…", "sizeBytes": 45000, "text": "^XA…^XZ" } ], "joined": "^XA…^XZ^XA…^XZ"}Warnings
Section titled “Warnings”An expression that fails does not fail the batch: the label still renders, with the same leniency as a single render (a failed content expression renders as empty text, a failed visibility expression leaves its element visible). Each failure is listed in warnings:
"warnings": [ { "index": 4, "elementId": "price", "message": "Cannot read properties of undefined (reading 'amount')" }]index is the item’s 0-based position in data, elementId the template element whose expression failed, and message the error. An empty list means every label is complete.
When a batch is refused or fails
Section titled “When a batch is refused or fails”A batch is checked as a whole before anything is rendered or counted. If the request has a problem, the whole batch is refused and nothing is rendered or counted:
| Problem | Response |
|---|---|
| More items than the plan allows | 400 BATCH_TOO_LARGE; details.items, details.limit, details.plan and details.upgradeUrl |
An entry in data that is not an object |
400 INVALID_BATCH_ITEM; details.index names the first one |
| An empty list | 400 BAD_REQUEST |
| A format that renders one label only | 400 INVALID_FORMAT |
png with "delivery": "inline" |
400 INLINE_NOT_SUPPORTED |
| Not enough renders left this month for every item | 429 QUOTA_EXCEEDED; the message says how many are left, and details.requested is the batch size |
A batch that fails as a whole after it was accepted (502 RENDER_ERROR, 502 CONTAINER_ERROR, 504 RENDER_TIMEOUT), or whose inline text is over 10 MB (400 INLINE_TOO_LARGE), delivers nothing and is not counted. A batch is never partly delivered or partly counted.
A batch request counts once toward your rate limit, whatever its size, and once per item toward your monthly quota.
Limits
Section titled “Limits”Every render request is checked against these limits before anything is rendered. A request outside a limit is refused with HTTP 400 and the code below, and it does not count toward your rate limit or monthly quota.
| Limit | Value | Code when exceeded |
|---|---|---|
DPI (dpi) |
50 to 600 |
400 DPI_OUT_OF_RANGE |
| Width and height | 1 to 1,500 mm each: the template size, and the media page and label |
400 SIZE_OUT_OF_RANGE |
| Total image size (PNG and ZPL) | 80 megapixels: width × height in pixels at the render’s DPI. For PNG of a sheet template this is the sheet page; otherwise the label. | 400 IMAGE_TOO_LARGE |
| Time per render | 30 seconds | 504 RENDER_TIMEOUT |
| Time per batch | 60 seconds | 504 RENDER_TIMEOUT |
| Items in a batch | Dev 10, Small 100; Big and Enterprise 250 for PDF and HTML, 100 for ZPL and PNG | 400 BATCH_TOO_LARGE |
| Text returned inline by a batch (ZPL, HTML) | 10 MB in total | 400 INLINE_TOO_LARGE |
For example, a 4 × 6 in label at 600 DPI is 2,400 × 3,600 px (8.6 megapixels), and a US Letter page at 600 DPI is 33.7 megapixels; both are well inside the limit. To fit a larger image, lower the dpi or the page size.
A render that runs longer than 30 seconds is stopped with 504 RENDER_TIMEOUT. It has already passed the limit checks, so it counts as one render. A batch that runs longer than 60 seconds is stopped the same way, and is not counted.
{ "error": "dpi must be a number from 50 to 600", "code": "DPI_OUT_OF_RANGE", "details": { "dpi": 1200, "limit": { "min": 50, "max": 600 } }}SIZE_OUT_OF_RANGE carries details.issues naming each field outside the limit (for example size.width or media.page.height). IMAGE_TOO_LARGE carries details.megapixels, widthPx, heightPx, dpi and limit.
The same size limit applies when you publish a template in the designer, which refuses sizes outside it.
Response — URL Delivery (default)
Section titled “Response — URL Delivery (default)”Status: 200 OK
{ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "complete", "format": "pdf", "url": "https://api.binderypress.dev/v1/render-outputs/a1b2c3d4-e5f6-7890-abcd-ef1234567890", "sizeBytes": 12345, "renderTimeMs": 450}| Field | Type | Description |
|---|---|---|
id |
string |
Unique render job ID (UUID). |
status |
string |
"complete". |
format |
string |
The output format. |
url |
string |
Download URL. Valid for 7 days. |
sizeBytes |
number |
Output file size in bytes. |
renderTimeMs |
number |
Time spent rendering in milliseconds. |
The response also includes rate limit headers.
Response — Inline Delivery
Section titled “Response — Inline Delivery”Status: 200 OK
The response body contains the rendered document directly. The Content-Type header matches the format:
| Format | Content-Type |
|---|---|
pdf |
application/pdf |
png |
image/png |
zpl |
text/plain |
html |
text/html |
Examples
Section titled “Examples”Render with a saved template (by slug)
Section titled “Render with a saved template (by slug)”curl -X POST https://api.binderypress.dev/v1/render \ -H "Authorization: Bearer bp_sk_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "templateId": "shipping-label", "data": { "orderNumber": "ORD-9876", "customer": "Acme Corp", "items": [ { "name": "Widget A", "qty": 10 }, { "name": "Widget B", "qty": 5 } ] }, "format": "pdf" }'Render inline template as PNG
Section titled “Render inline template as PNG”curl -X POST https://api.binderypress.dev/v1/render \ -H "Authorization: Bearer bp_sk_test_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "template": { "version": 2, "units": "in", "meta": { "name": "Badge" }, "size": { "width": 76.2, "height": 50.8 }, "elements": [ { "id": "name", "kind": "text", "position": { "x": 8, "y": 15 }, "size": { "width": 60, "height": 14 }, "expression": "attendeeName", "font": { "family": "Arial", "size": 20, "weight": "bold" }, "color": "#111111" } ] }, "data": { "attendeeName": "Jane Smith" }, "format": "png", "dpi": 150 }'Render ZPL for label printer (inline delivery)
Section titled “Render ZPL for label printer (inline delivery)”curl -X POST https://api.binderypress.dev/v1/render \ -H "Authorization: Bearer bp_sk_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "templateId": "label-template-id", "data": { "sku": "WIDGET-001", "quantity": 50 }, "format": "zpl", "dpi": 203, "delivery": "inline" }' \ -o label.zplRender a library template
Section titled “Render a library template”curl -X POST https://api.binderypress.dev/v1/render \ -H "Authorization: Bearer bp_sk_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "templateId": "carbon:product-2x1", "data": { "sku": "WIDGET-001", "name": "Widget A" }, "format": "pdf" }'Library templates use the librarySlug:templateSlug format. See Template Libraries for details.
Errors
Section titled “Errors”Schema validation errors use details.issues, an array of objects with path and message fields.
| Status | Code | Cause |
|---|---|---|
400 |
BAD_REQUEST |
Missing required fields or invalid format. |
400 |
V1_SCHEMA |
The inline template uses the legacy schema; this endpoint accepts schema v2 only. |
400 |
INVALID_TEMPLATE |
The inline template failed schema v2 validation. Check details.issues. |
400 |
DPI_OUT_OF_RANGE |
dpi is not a number from 50 to 600. See Limits. |
400 |
SIZE_OUT_OF_RANGE |
A width or height (template size, media page or label) is outside 1 to 1,500 mm. Check details.issues. |
400 |
EXPRESSION_NOT_ALLOWED |
An expression in the template (inline or saved) uses a word expressions may not use. The error names the word; details.issues gives each expression’s path. See Words Expressions May Not Use. |
400 |
IMAGE_TOO_LARGE |
PNG or ZPL output would exceed 80 megapixels at the requested DPI. |
400 |
INVALID_FORMAT |
The format is not supported, or data is a list and the format renders a single label. |
400 |
INVALID_SLOTS |
slots breaks a rule in Partial-sheet slots. |
400 |
BATCH_TOO_LARGE |
data holds more items than your plan renders in one request (Dev 10, Small 100; Big and Enterprise 250 for PDF and HTML, 100 for ZPL and PNG). See Batch. |
400 |
INVALID_BATCH_ITEM |
An entry in the data list is not an object. details.index names it. |
400 |
INLINE_NOT_SUPPORTED |
"delivery": "inline" with a list in data and format png. |
400 |
INLINE_TOO_LARGE |
A batch’s ZPL or HTML is over 10 MB, too much to return inline. Use URL delivery. Not counted. |
401 |
AUTH_REQUIRED |
Missing or invalid API key. |
403 |
SUSPENDED |
The account is suspended. Contact support@edgecraftstudio.com. |
404 |
NOT_FOUND |
Template ID not found (when using templateId). |
413 |
PAYLOAD_TOO_LARGE |
Request body exceeds 10 MB (1 MB for demo keys). |
429 |
RATE_LIMITED |
Too many requests. Retry after the Retry-After period. |
429 |
QUOTA_EXCEEDED |
Monthly renders used up: at the quota on Dev, at 120% of it on Small (never on Big). For a batch, also when fewer renders are left than it has items. The message and details.upgradeUrl point to the plans. See What Happens at the Quota. |
500 |
STORED_TEMPLATE_INVALID |
The saved template failed schema v2 validation. |
502 |
RENDER_ERROR |
Rendering failed. |
502 |
CONTAINER_ERROR |
No render container responded, even after one automatic retry on another container. Try again shortly. |
503 |
RATE_LIMITER_UNAVAILABLE |
Rate limiting is temporarily unavailable, so the request was not run. Retry after the Retry-After period. |
504 |
RENDER_TIMEOUT |
The render did not finish within 30 seconds (a batch: 60 seconds). |