> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pleo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate to the Export API (v3)

> Migration guide from the legacy Receipt API to the Export API (v3). Use it if you book expenses in an Accounting System. Receipts are Export Item attachments, only while the Export Job is pending or in_progress. For receipts outside an export, see the Accounting Entries guide.

This guide is for partners who used the [Receipt API](https://developers.pleo.io/reference/pleo-deprecated/receipts/get-expense-receipts.md) to fetch the receipts of expenses they book in an Accounting System. If you look up receipts outside an export, see [Migrate to the Accounting Entries API](https://developers.pleo.io/deprecation/legacy-receipt-api/migrate-to-accounting-entries-api.md) instead.

> **Use this page to answer:**

### Which API replaces the legacy Receipt API?

It depends on whether you run an export.

* If you book expenses in an Accounting System, use the Export API (v3). It provides receipts as attachments on Export Items.
* To get receipts outside an Export Job, use the Accounting Entries API.

The Export API (v3) is not a standalone receipt lookup. To choose, see the [Legacy Receipt API Overview](https://developers.pleo.io/deprecation/legacy-receipt-api/overview.md).

### How do I get receipts with the Export API (v3)?

Follow these steps:

1. Start the Export Job.
2. Fetch its Export Items with `GET /v3/export-items?job_id={jobId}`.
3. Read the `files[]` list on each item and download each file from its `url`.
4. Complete the job after the downloads.

Keep these limits in mind:

* You can only fetch Export Items while the job is `pending` or `in_progress`, so download the files before you complete the job.
* The `url` expires 24 hours after you fetch the items.
* An item has zero, one or several attachments. Each attachment can be up to 30 MB.

> **Sources for the Export API:**
>
> * OpenAPI reference: the endpoint pages under the [Export API Overview](https://developers.pleo.io/reference/export-api/export-api-overview.md). Use the v3 pages for new work. The [Export API Workflow](https://developers.pleo.io/reference/export-api/export-api-workflow.md) explains the order of the calls.
> * Attachments: [Attachments](https://developers.pleo.io/docs/current/platform/exports/attachments.md) explains the receipt file limits.
> * How-tos, all under `/docs/current/how-tos/accounting-integrations/`: [How to Detect and Start Export Jobs for Processing](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-detect-and-start-export-jobs-for-as-erp-processing.md), [How to Retrieve Export Job Items for Processing](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-retrieve-export-job-items-for-as-erp-processing.md), [How to Fetch Export Item Data for Processing](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-fetch-export-item-data-for-as-erp-processing.md), [How to Transfer Attachments](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-transfer-attachments-for-as-erp-processing.md), [How to Update Export Items](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-update-export-items-for-as-erp-processing.md) and [How to Update & Complete the Export Job](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-update-and-complete-export-job-for-as-erp-processing.md).
> * If a how-to and the reference disagree, trust the how-to. How-tos record tested behaviour.

> This page is the canonical source for getting receipts during an export, using the Export API v3. Related pages cover different concerns:
>
> * [Migrate to the Accounting Entries API](https://developers.pleo.io/deprecation/legacy-receipt-api/migrate-to-accounting-entries-api.md): reading receipts outside an export.
> * [Legacy Receipt API Overview](https://developers.pleo.io/deprecation/legacy-receipt-api/overview.md): helps you choose between the two.

## New to the Export API (v3)?

> [card] [Export Workflow Guide](https://developers.pleo.io/docs/current/guides/export-integration-workflow-guide.md)
>
> End-to-end walkthrough of the Export API (v3) integration model.

> [card] [Attachment Handling](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-attachment-handling.md)
>
> Rules for downloading, associating and storing attachments during an export.

> [card] [API Scopes](https://developers.pleo.io/reference/export-api/export-api-scopes.md)
>
> Required scopes: `export-jobs:write`, `export-jobs:read`, `export-items:read`.

> [card] [OAuth Guide](https://developers.pleo.io/docs/current/guides/oauth-workflow-guide.md)
>
> End-to-end OAuth 2.0 workflow guide for Pleo integrations.

> [card] [Standalone API Key Guide](https://developers.pleo.io/docs/current/guides/standalone-api-keys-workflow-guide.md)
>
> End-to-end guide for authenticating with standalone API keys.

> [card] [Migrate from the Expenses API](https://developers.pleo.io/deprecation/legacy-expense-api/migration-guide-expenses-api-to-export-api.md)
>
> The full export steps for integrations that used the Expenses API.

## What Changes in Your Integration

The Export API (v3) is not a standalone receipt lookup. Pleo now provides each receipt as an attachment on an Export Item. You fetch the Export Items of an Export Job, so the attachments arrive in that response. You no longer call a separate receipt endpoint for each expense.

| Step | Before (Receipt API) | After (Export API v3) |
| :- | :- | :- |
| Start the work | Not applicable | `POST /v3/export-job-events` with `"event": "started"` |
| Find the receipts | `GET /expenses/{expenseId}/receipts` for each expense | `GET /v3/export-items?job_id={jobId}` for the whole Export Job |
| Read a receipt | `url` on each receipt | `url` on each entry of `files[]` |
| Download the receipt | Download from the `url` | Download from the `url` |

### Fetching Attachments

1. Detect a `pending` Export Job and start it with `POST /v3/export-job-events` and `"event": "started"`. The Export Job is now `in_progress`.
2. Fetch the Export Items with `GET /v3/export-items?job_id={jobId}`. This endpoint is paginated. Use `limit` to set the page size. To read the next page, send the `endCursor` from the response as `after`, until `hasNextPage` is `false`.
3. Read the `files[]` list on each Export Item. Each entry has a `url`, a `type` and a `size`.
4. Download each attachment from its `url`. Then upload it to the entry that you create in the Accounting System.

You need the `export-jobs:write` scope to start the Export Job and the `export-items:read` scope to fetch the Export Items.

An Export Item has zero, one or several attachments. Pleo includes an attachment only if the file is available at export time and the Export Item passes validation. The maximum size is 30 MB per attachment. Your integration decides whether a missing attachment is an error. For the rules on downloading, merging and retrying, see [How to Transfer Attachments](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-transfer-attachments-for-as-erp-processing.md).

Note

The `url` of each attachment expires 24 hours after you fetch the Export Items, so download the files promptly.\
\
You can only fetch Export Items while the Export Job is `pending` or `in_progress`. Download the attachments before you complete the Export Job.

[Get Export Items →](https://developers.pleo.io/reference/export-api/export-items-v3/get-export-items.md)

## Field Mapping

The table below maps fields from the legacy `Receipt` model to their equivalents in the `files[]` entries of an Export Item.

* `—` : field is not available in the Export API (v3)
* `*` : data is the same but represented differently

| `Receipt` field | `files[]` equivalent | Description |
| :- | :- | :- |
| id | — | The legacy receipt had its own `id`. An attachment has no `id`, so use the `accountingEntryId` of its Export Item to link it to an expense. |
| name | — | The legacy file name. The Export API (v3) does not return one. |
| url | url **\*** | Where to download the file. The `url` now stays valid for 24 hours instead of 15 hours. |
| mimeType | type | The file type, usually a MIME type such as `application/pdf`. |
| size | size **\*** | The file size. It is now in bytes instead of kilobytes. |

[Attachment Handling Integration Design →](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-attachment-handling.md)
