# Download a credit note PDF

> The credit_notes.pdf operation: GET /api/v1/credit_notes/{id}/pdf in the REST API and the credit_notes_pdf tool in the MCP server.

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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).