Batches API

Render many documents in a single background job. You submit a list of document data payloads, InvoicePDFs renders each one to a PDF, and you poll the batch until it completes, then download all the renders as a single ZIP archive.

Create Batch

POST /api/v1/batches

Request:

{
  "operation": "render",
  "template_id": "tpl_modern",
  "items": [
    {
      "external_id": "order_1001",
      "document_type": "invoice",
      "data": { }
    }
  ],
  "output": {
    "format": "pdf",
    "combine": false,
    "archive_format": "zip"
  }
}

Field	Required	Description
operation	No	Operation to perform. Only render is supported (default)
items	Yes	List of items to render (at least one)
items[].external_id	No	Your own identifier for the item; used as the PDF filename in the download archive
items[].document_type	No	Document type for the item. Only invoice is supported (default)
items[].data	Yes	Document data payload to render
template_id	No	Template to render every item with (default tpl_modern)
output	No	Output options for the batch
output.format	No	Output format. Only pdf is supported (default)
output.combine	No	Combine all renders into a single file (default false)
output.archive_format	No	Archive format for the download. Only zip is supported (default)

Response 200 OK:

{
  "data": {
    "id": "batch_01XYZ",
    "status": "queued",
    "operation": "render",
    "template_id": "tpl_modern",
    "total_items": 1,
    "completed_items": 0,
    "failed_items": 0,
    "created_at": "2026-07-20T10:00:00Z",
    "updated_at": "2026-07-20T10:00:00Z",
    "completed_at": null
  }
}

The batch is processed in the background. Poll Get Batch until status is completed or failed.

Try it

List Batches

GET /api/v1/batches?limit=50

Response:

{
  "data": [
    {
      "id": "batch_01XYZ",
      "status": "completed",
      "operation": "render",
      "template_id": "tpl_modern",
      "total_items": 1,
      "completed_items": 1,
      "failed_items": 0,
      "created_at": "2026-07-20T10:00:00Z",
      "updated_at": "2026-07-20T10:01:00Z",
      "completed_at": "2026-07-20T10:01:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

Try it

Get Batch

GET /api/v1/batches/{batch_id}

Response:

{
  "data": {
    "id": "batch_01XYZ",
    "status": "processing",
    "operation": "render",
    "template_id": "tpl_modern",
    "total_items": 10,
    "completed_items": 4,
    "failed_items": 0,
    "created_at": "2026-07-20T10:00:00Z",
    "updated_at": "2026-07-20T10:00:30Z",
    "completed_at": null
  }
}

Try it

List Batch Items

GET /api/v1/batches/{batch_id}/items?limit=50

Returns the individual items in a batch and their per-item render status.

Response:

{
  "data": [
    {
      "id": "bi_01XYZ",
      "external_id": "order_1001",
      "document_type": "invoice",
      "status": "completed",
      "render_id": "rnd_01ABC",
      "error_message": null,
      "created_at": "2026-07-20T10:00:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

Try it

Cancel Batch

POST /api/v1/batches/{batch_id}/cancel

Cancels a batch that is still queued or processing. Any items that have not yet been rendered are marked as failed. A batch that is already completed, failed, or cancelled returns a 409 conflict error.

Response:

{
  "data": {
    "id": "batch_01XYZ",
    "status": "cancelled",
    "operation": "render",
    "template_id": "tpl_modern",
    "total_items": 10,
    "completed_items": 4,
    "failed_items": 6,
    "created_at": "2026-07-20T10:00:00Z",
    "updated_at": "2026-07-20T10:00:45Z",
    "completed_at": "2026-07-20T10:00:45Z"
  }
}

Try it

Download Batch

GET /api/v1/batches/{batch_id}/download

Returns a ZIP archive (application/zip) containing one PDF per completed item. Each file is named after the item's external_id (falling back to the item ID) with a .pdf extension.

Downloads are only available once the batch status is completed; any other status returns a 409 conflict error. If the batch has no completed renders, a 404 not_found error is returned.

Content-Type: application/zip
Content-Disposition: attachment; filename="batch_01XYZ.zip"

Try it

Batch Statuses

Status	Description
queued	Batch has been accepted and is waiting to be processed
processing	Items are being rendered
completed	All items have finished processing
failed	Batch processing failed
cancelled	Batch was cancelled before all items completed