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

> How to migrate an existing Expenses API integration to the Export API.

export const WhatComesNext = ({children, href}) => <div className="mt-4">
    <a href={href} className="
        inline-flex items-center justify-center
        rounded-full
        bg-black text-white dark:bg-[#1f262b]
        px-5 py-2.5 text-sm font-medium
        no-underline border-0
        hover:bg-[#ffe6ea] dark:hover:bg-[#2b1f23]
        hover:text-black
        transition-colors
      ">
      {children} →
    </a>
  </div>;

This guide is for partners who used the [Expenses API](/reference/pleo-deprecated/expenses/get-an-expense-for-a-company) to build custom export integrations to accounting systems. If you were fetching expense data for other workflows, see [Migrate to the Accounting Entries API](/deprecation/legacy-expense-api/migrate-to-accounting-entries-api) instead.

## New to the Export API?

<CardGroup cols={3}>
  <Card title="Export Workflow Guide" icon="route" href="/docs/current/guides/export-integration-workflow-guide">
    <div className="text-sm mt-2">End-to-end walkthrough of the Export API integration model.</div>
  </Card>

  <Card title="Integration Design" icon="ruler" href="/docs/current/integration-design/exports/integration-design-exports-overview">
    <div className="text-sm mt-2">Rules and requirements for each part of an export integration.</div>
  </Card>

  <Card title="Connect Pleo to a Custom API Integration" icon="gear" href="/docs/current/how-tos/accounting-integrations/how-to-connect-pleo-to-a-custom-api-integration">
    <div className="text-sm mt-2">How to connect Pleo to route exports to your custom integration.</div>
  </Card>
</CardGroup>

<CardGroup cols={3}>
  <Card title="API Scopes" icon="lock" href="/reference/export-api/export-api-scopes">
    <div className="text-sm mt-2">Required scopes: `export-jobs:write`, `export-jobs:read`, `export-items:read`.</div>
  </Card>

  <Card title="OAuth Guide" icon="shield" href="/docs/current/guides/oauth-workflow-guide">
    <div className="text-sm mt-2">End-to-end OAuth 2.0 workflow guide for Pleo integrations.</div>
  </Card>

  <Card title="OAuth with Postman" icon="paper-plane" href="/docs/current/guides/oauth-workflow-guide-postman">
    <div className="text-sm mt-2">How to configure Postman to authenticate using OAuth and call the Pleo API.</div>
  </Card>

  <Card title="Standalone API Key Guide" icon="key" href="/docs/current/guides/standalone-api-keys-workflow-guide">
    <div className="text-sm mt-2">End-to-end guide for authenticating with standalone API keys.</div>
  </Card>

  <Card title="Standalone API Keys with Postman" icon="paper-plane" href="/docs/current/how-tos/api-keys/how-to-make-an-api-call-using-standalone-api-keys-postman">
    <div className="text-sm mt-2">How to make API calls using standalone API keys in Postman.</div>
  </Card>
</CardGroup>

## What Changes in Your Integration

The table below gives a quick overview of how each step maps from the Expenses API to the Export API.

| Step                                             | Before (Expenses API)                             | After (Export API)                                                              |
| :----------------------------------------------- | :------------------------------------------------ | :------------------------------------------------------------------------------ |
| [Detect new exports](#detecting-new-exports)     | Poll `GET /v1/expenses?status=QUEUED`             | Listen for `v1.export.job-created` webhook                                      |
| [Start a job](#starting-a-job)                   | Not applicable                                    | `POST /v3/export-job-events` with `"event": "started"`                          |
| [Fetch items](#fetching-export-items)            | `GET /v1/expenses?status=QUEUED`                  | `GET /v3/export-jobs/{jobId}/items`                                             |
| [Process export items](#processing-export-items) | At integration's discretion                       | Integration design guidelines and workflow guide                                |
| [Update item status](#updating-item-status)      | `PUT /v1/expenses` with `{"status": "EXPORTING"}` | `PUT /v3/export-jobs/{jobId}/items` with granular statuses                      |
| [Complete the export](#completing-the-export)    | `PUT /v1/expenses` with `{"status": "EXPORTED"}`  | Update item statuses + `POST /v3/export-job-events` with `"event": "completed"` |

The following sections cover each change in detail.

### Detecting New Exports

**Before:**

```http theme={null}
GET /v1/expenses?status=QUEUED
```

**After:** Listen for the `v1.export.job-created` [webhook event](/reference/overview-webhooks).

<WhatComesNext href="/docs/current/how-tos/accounting-integrations/how-to-detect-and-start-export-jobs-for-as-erp-processing#1-detect-available-export-jobs">
  How to Detect Available Export Jobs
</WhatComesNext>

### Starting a Job

**Before:** Not applicable.

**After:** Create a `started` event to claim the job before processing.

```http theme={null}
POST https://external.pleo.io/v3/export-job-events
Content-Type: application/json

{
    "event": "started",
    "jobId": "[JOB_ID]"
}
```

<WhatComesNext href="/docs/current/how-tos/accounting-integrations/how-to-detect-and-start-export-jobs-for-as-erp-processing#5-start-the-export-job">
  How to Start the Export Job
</WhatComesNext>

### Fetching Export Items

**Before:**

```http theme={null}
GET https://openapi.pleo.io/v1/expenses?status=QUEUED
```

**After:**

```http theme={null}
GET https://external.pleo.io/v3/export-jobs/[JOB_ID]/items
```

<WhatComesNext href="/docs/current/how-tos/accounting-integrations/how-to-retrieve-export-job-items-for-as-erp-processing">
  How to Retrieve Export Job Items
</WhatComesNext>

### Processing Export Items

**Before:** At integration's discretion.

**After:** Pleo provides integration design guidelines and a dedicated workflow guide covering bookkeeping methods, accounts mapping, data mapping, attachments, and posting behaviour.

<WhatComesNext href="/docs/current/integration-design/exports/integration-design-exports-overview">
  AS/ERP Integration Design
</WhatComesNext>

<WhatComesNext href="/docs/current/guides/accounting-system-processing-workflow-guide">
  AS/ERP Processing Workflow Guide
</WhatComesNext>

### Updating Item Status

**Before:**

```http theme={null}
PUT https://openapi.pleo.io/v1/expenses
Content-Type: application/json

{"status": "EXPORTING"}
```

**After:** Update individual items with granular statuses (`in_progress`, `successful`, `failed`, or `abandoned`).

```http theme={null}
PUT https://external.pleo.io/v3/export-jobs/[JOB_ID]/items
Content-Type: application/json

[
    {"accountingEntryId": "[ITEM_ID]", "status": "in_progress"}
]
```

<WhatComesNext href="/docs/current/how-tos/accounting-integrations/how-to-update-export-items-for-as-erp-processing">
  How to Update Export Items
</WhatComesNext>

### Completing the Export

**Before:**

```http theme={null}
PUT https://openapi.pleo.io/v1/expenses
Content-Type: application/json

{"status": "EXPORTED"}
```

**After:** Update item statuses to their final state, then create a `completed` event.

```http theme={null}
PUT https://external.pleo.io/v3/export-jobs/[JOB_ID]/items
Content-Type: application/json

[
    {
        "accountingEntryId": "[ITEM_ID]",
        "status": "successful",
        "exportedAt": "2025-07-31T12:48:52.236Z",
        "externalId": "[ENTRY_ID_IN_YOUR_ACCOUNTING_SYSTEM]",
        "externalUrl": "[ENTRY_URL_IN_YOUR_ACCOUNTING_SYSTEM]"
    }
]
```

```http theme={null}
POST https://external.pleo.io/v3/export-job-events
Content-Type: application/json

{
    "event": "completed",
    "jobId": "[JOB_ID]"
}
```

<WhatComesNext href="/docs/current/how-tos/accounting-integrations/how-to-update-and-complete-export-job-for-as-erp-processing">
  How to Update and Complete Export Jobs
</WhatComesNext>

## Data Model Changes

The table below maps fields from the `Expense` model to their equivalents in the `Export Item` model.

* `—` : field is not available in the Export Item model
* `*` : data is the same but represented differently. See the [Export Item API reference](/reference/export-api/export-api-v3/get-export-job-items) for details.
* `**` : resolved entity relationship: the associated data is included directly, removing the need for additional API calls

| `Expense` field               | `Export Item` equivalent                           |
| :---------------------------- | :------------------------------------------------- |
| id                            | accountingEntryId                                  |
| employeeId                    | user.id                                            |
| employeeCode                  | user.code                                          |
| departmentId                  | team.id                                            |
| performedAt                   | date                                               |
| amountOriginal                | —                                                  |
| amountSettled                 | amount **\***                                      |
| note                          | note                                               |
| type                          | type **\***                                        |
| accountId                     | accountingEntryLines\[].account.id                 |
| taxCodeId                     | accountingEntryLines\[].tax.id                     |
| createdAt                     | date **\*\***                                      |
| updatedAt                     | date **\*\***                                      |
| deletedAt                     | —                                                  |
| tagIds\[].id                  | accountingEntryLines\[].tags\[].id                 |
| tagIds\[].tagGroupId          | accountingEntryLines\[].tags\[].groupCode **\*\*** |
| receiptIds\[]                 | files\[] **\*\***                                  |
| settledExpenseIds\[]          | additionalInformation.reconciledEntries\[]         |
| status                        | —                                                  |
| supplier.CIF                  | supplier.taxIdentifier                             |
| supplier.documentNumber       | —                                                  |
| cardTransaction.state         | —                                                  |
| cardTransaction.authorizedAt  | —                                                  |
| cardTransaction.settledAt     | date                                               |
| cardTransaction.reversedAt    | —                                                  |
| cardTransaction.merchant.id   | vendor.id                                          |
| cardTransaction.merchant.name | vendor.name                                        |
| lines\[].amountSettled        | accountingEntryLines\[].lineAmount                 |
| lines\[].accountId            | accountingEntryLines\[].account.id                 |
| lines\[].taxCodeId            | accountingEntryLines\[].tax.id                     |
| lines\[].tagIds\[]            | accountingEntryLines\[].tags\[].id                 |

<WhatComesNext href="/docs/current/integration-design/exports/integration-design-exports-data-mapping">
  Data Mapping Integration Design
</WhatComesNext>