Download an invoice PDF · Ownrecord docs

Downloads the PDF of an invoice or receipt of the brand. Over REST the response is the PDF itself (Content-Type: application/pdf, ETag = its SHA-256, Content-Disposition with the invoice number); MCP clients get the file's metadata and download URL.

The PDF is rendered once, right after issue, from the invoice as issued, and never changes: the stored file is checked against the SHA-256 recorded on the invoice before it is served. Until it is rendered the call answers invoice_pdf_not_ready (retryable).

At a glance

REST: GET /api/v1/invoices/{id}/pdf
MCP tool: invoices_pdf
Operation ID: invoices.pdf
Scope: Brand
Permission: invoices:read
Risk tier: read
Dry run: Not supported
Idempotency: Not needed (read only)
Modes: Test and live
Authentication: API key with the invoices:read scope
Since: M4

Request

Path parameters

Field	Type	Description
`id`	`inv_…` ID	The invoice ID (`inv_…`).

Query parameters

This operation takes no query parameters.

Response

200 OK with a JSON object:

Field	Type	Description
`object`	`"invoice_pdf"`
`invoiceId`	`inv_…` ID
`number`	string
`fileId`	`file_…` ID
`contentType`	`"application/pdf"`
`filename`	string
`size`	integer
`sha256`	string
`templateVersion`	integer
`url`	string	Where to download the bytes with the same credentials.

Examples

The PDF of a receipt

Over REST the body is the PDF; this is the metadata MCP clients see.

HTTP

GET /api/v1/invoices/inv_01m4tx5nj8emwbyf7y9vcf47yb/pdf
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "object": "invoice_pdf",
  "invoiceId": "inv_01m4tx5nj8emwbyf7y9vcf47yb",
  "number": "GEN-2026-000123",
  "fileId": "file_01m4tx5nj8emwbyf7y9vcf47yg",
  "contentType": "application/pdf",
  "filename": "GEN-2026-000123.pdf",
  "size": 27265,
  "sha256": "4f1c3c3e6a2f0b9d8e7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e",
  "templateVersion": 1,
  "url": "/api/v1/invoices/inv_01m4tx5nj8emwbyf7y9vcf47yb/pdf"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	`id` isn't an invoice ID (`inv_…`).	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	This brand has no such numbered invoice in this mode (a draft has no PDF until it's finalized).	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`scope_required`	400	The request names no brand (an org or entity key without `Ownrecord-Brand`).	Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`).
`permission_denied`	403	You can't read this brand's invoices (`invoices:read`; every role but billing admin has it).	Ask an organization owner or admin for a role or scope that allows this action.
`livemode_not_allowed`	403	You have no live-mode access, so you can't use live invoices.	Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin.
`invoice_pdf_not_ready`	409	The PDF is still being rendered (right after issue); try again shortly.	The PDF is rendered right after the invoice is issued, usually within a minute. Try again shortly; `pdf.status` on the invoice says when it's ready.
`invoice_pdf_unavailable`	500	The stored file couldn't be read or doesn't match its SHA-256 (download route only); try again later.	Try again in a few minutes. If it keeps failing, contact support with the request ID: the file is checked against its stored SHA-256 and never served when it differs.

It can also return these common errors: api_version_unsupported, authentication_required, api_key_invalid, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Query parameters#

Response#

Examples#

The PDF of a receipt#

Errors#