Download a credit note PDF · Ownrecord docs

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

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

At a glance

REST: GET /api/v1/credit_notes/{id}/pdf
MCP tool: credit_notes_pdf
Operation ID: credit_notes.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: M8

Request

Path parameters

Field	Type	Description
`id`	`cn_…` ID	The credit note ID (`cn_…`).

Query parameters

This operation takes no query parameters.

Response

200 OK with a JSON object:

Field	Type	Description
`object`	`"credit_note_pdf"`
`creditNoteId`	`cn_…` 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 credit note

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

HTTP

GET /api/v1/credit_notes/cn_01m5cg0f7aex3sxj6q2wq1ha2d/pdf
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "object": "credit_note_pdf",
  "creditNoteId": "cn_01m5cg0f7aex3sxj6q2wq1ha2d",
  "number": "GEN-CN-2026-000004",
  "fileId": "file_01m5cg0f7aex3sxj6q2wq1ha2j",
  "contentType": "application/pdf",
  "filename": "GEN-CN-2026-000004.pdf",
  "size": 31208,
  "sha256": "9e2a6c1b0d4f3e2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a",
  "templateVersion": 1,
  "url": "/api/v1/credit_notes/cn_01m5cg0f7aex3sxj6q2wq1ha2d/pdf"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	`id` isn't a credit note ID (`cn_…`).	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	This brand has no such credit note in this mode.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`credit_note_pdf_not_ready`	409	The PDF is rendered right after the credit note is issued; try again shortly.	The PDF is rendered right after the credit note is issued, usually within a minute. Try again shortly; `pdf.status` on the credit note says when it's ready.
`credit_note_pdf_unavailable`	500	The stored file is missing or doesn't match its SHA-256 (the REST download only).	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.
`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 credit notes (`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 refunds or credit notes.	Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin.

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 credit note#

Errors#