Skip to content

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/render

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"
}
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.

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 1 is the top-left cell.
  • On a 2-column grid, slot 2 is the top-right cell; slot 3 is 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.

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).

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).

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.

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.

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.

With "delivery": "inline":

  • pdf returns the document itself as the body, Content-Type: application/pdf, as a single render does. The X-Batch-Id header carries the batch ID and X-Render-Warnings the number of warnings; use URL delivery to see the warnings themselves.
  • zpl and html return the JSON above, without the URLs: each entry in items has index, id, sizeBytes and text, the label’s ZPL or HTML. For zpl, joined holds every block joined in input order. Inline results are not kept, so they have no download link.
  • png is 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"
}

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.

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.

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.

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.

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
Terminal window
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"
}'
Terminal window
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)”
Terminal window
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.zpl
Terminal window
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.

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).