Bulk PDF files export
Bulk PDF export generates ZIP files of invoice, credit memo, and debit memo PDFs for the document IDs you provide. The API does not filter documents, so you must preselect IDs and manage missing or archived PDFs before export.
Bulk PDF export creates ZIP files containing PDFs for the billing document IDs you provide. The Bulk PDF API does not select or filter invoices, credit memos, or debit memos; filter the document IDs before you submit the request.
The bulk export feature is designed for invoices created manually by users. It does not include invoices generated automatically by the system, such as invoices created after a payment is processed. For a complete export that includes manually created and system-generated invoices, use Data Exports.
Use the Bulk PDF API to trigger a high-volume or automated job, and use the job retrieval operation to monitor its status. Before submitting a job, check PDF status and decide how to handle missing and archived PDFs.
Choose an export method
Use the method that matches your task:
Task | Method |
|---|---|
| View an invoice or access its PDF from the invoice record | Open the invoice details page and review PDF Generation Status. If the PDF is archived, use Restore on the associated invoice record, when available. |
| Run an interactive Invoice PDF export from the Zuora UI | Use the Invoice PDF option in Data Exports. The user must have a Reporting role with the Enable Exports permission. See Data Exports. |
| Trigger or monitor a bulk PDF generation job | Use POST /v1/operations/bulk-pdf and GET /v1/operations/bulk-pdf/{jobId}. These job operations are API-only. The Data Exports UI is a separate capability. |
The Bulk PDF API accepts document IDs rather than invoice filters. If you need all invoices, including system-generated invoices, use the Data Exports capability described above rather than assuming the Bulk PDF API will select them.
Check PDF status and handle archived PDFs
Call GET /v1/invoices/pdf-status to check invoice PDF status before a bulk export. The operation accepts up to 50 invoice IDs or numbers in each request. The pdfGenerationStatus values are None, Pending, Processing, Generated, Error, Obsolete, and Archived.
Archived means that a PDF changed from Generated to Archived when the file was archived. The file cannot be used directly until it is restored. Obsolete means that an update was applied to the document; for example, a payment was applied or a custom field was updated.
generateMissingPDF=true generates a PDF for a document that does not already have one. It does not restore an archived PDF. To include an archived PDF, restore the archived file first by using PUT /v1/files/{file-id}/restore. Restoration is asynchronous and can take 12 to 48 hours. Monitor GET /v1/files/{file-id}/status until the file status is RESTORED before relying on the file for export.
If archived PDFs should be skipped rather than restored, set ignoreArchivedFiles=true if that parameter is supported by the API version used by your integration. Otherwise, restore the required files before submitting the bulk export. Purged files cannot be restored. For retention details, see File retention policy.
Considerations for Large or Multi-Year PDF Exports
Use this checklist for a large or multi-year export:
- Define the invoice population and date range. Filter the document IDs outside the Bulk PDF API because the API does not filter invoices.
- Check PDF status using
GET /v1/invoices/pdf-status. Submit no more than 50 invoice IDs or numbers in each status request. - Separate invoices by status. Wait and check again for
PendingorProcessingPDFs. Review the error details forErrorPDFs. Confirm whetherObsoletePDFs need to be regenerated or otherwise addressed. - For each
ArchivedPDF that must be included, identify its file ID and callPUT /v1/files/{file-id}/restore. Restoration can take 12 to 48 hours; poll the file status until it isRESTOREDbefore starting the export. If the request should omit archived PDFs, useignoreArchivedFiles=trueonly when supported by the API version in use. - Decide whether to set
generateMissingPDF=truefor documents that have no generated PDF. This parameter does not restore archived files. - Divide the export into requests of no more than 50,000 document IDs. Expect up to 1,000 document IDs in each generated ZIP file.
- Poll the job status and download every ZIP file promptly. The current FAQ states that pre-signed URLs expire after one hour and generated ZIP files are retained for one day; do not assume an expired URL can be regenerated.
- Retain the input document list, job ID, index files, and failed or skipped document details with your export records.