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

# Attaching receipts to expenses

> Learn how to upload a receipt file and attach it to an expense when using the Expenses API.

When an expense nature requires a receipt (i.e. the receipt is mandatory), you must follow a **three-step process** to attach it. You cannot pass a file upload ID directly in the `expenseReceipts` array — doing so will result in a `403 Forbidden` error.

## Step 1 — Upload the file

First, upload the receipt file (image, PDF, etc.) using the [Files API](/api-reference/legacy/files/post-upload):

<CodeGroup>
  ```http Upload a file theme={null}
  POST /lucca-files/api/uploads HTTP/2
  Host: example.ilucca.net
  Authorization: lucca application={API_KEY}
  Accept: application/json
  Content-Type: multipart/form-data; boundary=----FormBoundary

  ------FormBoundary
  Content-Disposition: form-data; name="form"; filename="receipt.pdf"
  Content-Type: application/pdf

  < ./receipt.pdf
  ------FormBoundary--
  ```

  ```json Response (201 Created) theme={null}
  {
    "id": "a24f4279-6bb4-4e1c-9b40-a80a5d44b36d",
    "name": "receipt.pdf",
    "createdAt": "2025-06-15T10:30:00Z",
    "deletedAt": null,
    "contentLength": 95683,
    "contentType": "application/pdf",
    "extension": ".pdf",
    "totalPages": 1
  }
  ```
</CodeGroup>

Save the returned `id` — this is your `uploadId` for the next step.

## Step 2 — Create an ExpenseReceipt

Next, create an `ExpenseReceipt` resource by calling `POST /api/v3/expenseReceipts`. This step links the uploaded file to the Expenses module:

<CodeGroup>
  ```http Create an ExpenseReceipt theme={null}
  POST /api/v3/expenseReceipts HTTP/2
  Host: example.ilucca.net
  Authorization: lucca application={API_KEY}
  Content-Type: application/json

  {
    "ownerId": 123,
    "requiresOcr": false,
    "sourceId": "WebForm",
    "uploadId": "a24f4279-6bb4-4e1c-9b40-a80a5d44b36d"
  }
  ```

  ```json Response (200 OK) theme={null}
  {
    "id": "f0d01fd0-5f27-4061-8dca-bee6318b0103",
    "originalReceipt": {
      "id": "cb0aae89-56c9-48db-9052-48981660e0f7",
      "name": "receipt-f0d01fd0-5f27-4061-8dca-bee6318b0103.pdf",
      "href": "https://example.ilucca.net/api/v3/ExpenseReceipts/f0d01fd0-5f27-4061-8dca-bee6318b0103/originalReceiptFile",
      "extension": ".pdf"
    }
  }
  ```
</CodeGroup>

| Property      | Type            | Description                                                                                                              |
| :------------ | :-------------- | :----------------------------------------------------------------------------------------------------------------------- |
| `ownerId`     | `integer`       | The user ID of the expense owner. Must match the owner of the expense you will create at the next step.                  |
| `requiresOcr` | `boolean`       | Set to `true` if you want Lucca to run OCR (optical character recognition) on the receipt to automatically extract data. |
| `sourceId`    | `string`        | The source of the receipt. Use `"WebForm"` when creating via API.                                                        |
| `uploadId`    | `string (uuid)` | The `id` returned by `/lucca-files/api/uploads` in step 1.                                                               |

Save the returned `id` (here `f0d01fd0-...`) — this is the **ExpenseReceipt ID** you will reference in the expense.

## Step 3 — Create the expense with the receipt attached

Finally, create the expense via `POST /api/v3/expenseTempItems`, referencing the `ExpenseReceipt` by its `id`:

<CodeGroup>
  ```http Create expense with receipt theme={null}
  POST /api/v3/expenseTempItems HTTP/2
  Host: example.ilucca.net
  Authorization: lucca application={API_KEY}
  Content-Type: application/json

  {
    "expenseNatureId": 1,
    "purchasedOn": "2025-06-15",
    "paymentMethodId": 0,
    "quantity": 1,
    "originalTransaction": {
      "currencyId": "EUR",
      "grossAmount": 42.50
    },
    "processedAmounts": {
      "grossAmount": 42.50,
      "currencyId": "EUR"
    },
    "deviceId": "Web",
    "ownerId": 123,
    "merchant": "Restaurant ABC",
    "comment": "Business lunch",
    "expenseReceipts": [
      { "id": "f0d01fd0-5f27-4061-8dca-bee6318b0103" }
    ]
  }
  ```
</CodeGroup>

<Warning>
  **Do not** pass the file upload ID (from step 1) directly in `expenseReceipts`. You must create an `ExpenseReceipt` resource first (step 2) and reference *that* ID. Passing the upload ID directly will result in a `403 Forbidden` error with the message: *"Property Id of type CleemyFile is not writable"*.
</Warning>

## Summary

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Files as /lucca-files/api/uploads
    participant Receipts as /api/v3/expenseReceipts
    participant Expenses as /api/v3/expenseTempItems

    Client->>Files: POST (multipart file)
    Files-->>Client: uploadId

    Client->>Receipts: POST { ownerId, uploadId, ... }
    Receipts-->>Client: ExpenseReceipt (id)

    Client->>Expenses: POST { ..., expenseReceipts: [{ id }] }
    Expenses-->>Client: ExpenseTempItem created
```