API Background rendering · 7 min read

Async Renders

Submit a stored render, receive its request id after BladePDF has validated and accepted it within your workspace capacity, and continue your application flow without waiting for the generated PDF.

Submit an async render

Finish the fluent render builder with async(). Every asynchronous render must call storePdf() because no PDF bytes are returned in the HTTP response.

Queue an invoice render

php

 1$submission = BladePDF::fromTemplate('invoice.standard', $context)
 2    ->reference($invoice->uuid)
 3    ->storePdf()
 4    ->webhook(
 5        route('webhooks.bladepdf'),
 6        config('services.bladepdf.webhook_secret'),
 7    )
 8    ->async();

Storage is required

Calling async() without storePdf() throws InvalidRenderConfigurationException before the package sends a request. The API also rejects async submissions when the workspace storage quota is full.

Accepted response

BladePDF returns 202 Accepted after the request has been authenticated, the request body has been parsed and validated, storage has been checked, and the render has been accepted for background processing. The Laravel package exposes the JSON response as a RenderSubmission object.

Async still uses your workspace capacity

An async request can wait before it receives 202 Accepted if your workspace is already using all available concurrency. Async delivery is intended for long-running or large PDFs where you do not want to keep waiting for generation after the render has been accepted; it is not a way to skip capacity limits.

Correlate the queued render

php

 1$submission->requestId; // BladePDF request id
 2$submission->reference; // Your reference, or null

Property	Type	Purpose
`requestId`	`string`	Correlates the accepted request with render history and webhook events.
`reference`	`?string`	Echoes the value supplied through `reference()`.

What happens after acceptance

The render has already passed request validation, storage checks, and capacity admission.
The PDF is generated in the background.
The generated PDF is persisted to workspace storage.
BladePDF records a pdf.rendered or pdf.failed event.
Dashboard endpoints and the optional per-request webhook are notified.

Configure a dashboard webhook endpoint for account-wide notifications. Use webhook() in the async call when the result should go to an endpoint chosen specifically for that render.

Synchronous and asynchronous failures

When	How it is reported
Before acceptance	`async()` throws for invalid configuration, authentication, payload, storage quota, or capacity errors. If all concurrency slots are busy but the request can still wait, the HTTP request may stay open until capacity is available.
After `202 Accepted`	The render result is recorded and delivered as a `pdf.rendered` or `pdf.failed` event.

REST API

Non-Laravel clients request the same behavior with Prefer: respond-async, Accept: application/json, and store_pdf=1. See the REST API async example for the complete multipart request and response.