> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.deel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_mcp/server.

# Reimburse employee expenses

## Overview

This guide walks you through the complete process of reimbursing business expenses for payroll employees using the adjustments API. You will learn how to submit expense reimbursements with supporting documentation, track approval workflows, and ensure timely payment through the regular payroll cycle.

## When to use this workflow

Use this workflow when you need to:

* Reimburse employees for travel expenses (flights, accommodation, transportation)
* Pay back equipment purchases (laptops, monitors, office supplies)
* Compensate for client meals and entertainment expenses
* Process mileage or vehicle allowances
* Refund any business-related expenses paid by employees

## Prerequisites

Before you begin, ensure you have:

* A valid API token with `adjustments:write` scope
* The `contract_id` of the employee receiving the reimbursement
* Expense details (amount, category, date, description)
* Supporting documents (receipts, invoices) uploaded to a file storage service

> **Note**
>
> Expense reimbursements are processed through the regular payroll cycle. Submit reimbursements
> before the payroll cutoff date to ensure they appear on the next payslip.

## Step-by-step workflow

This example demonstrates reimbursing an employee \$345.67 for a business trip, including flight and accommodation costs.

### Identify the employee contract

First, retrieve the contract ID for the employee receiving the reimbursement. You can list contracts and filter by employee email or employee number.

```shell
curl --request GET 'https://api.letsdeel.com/rest/contracts?status=active&type=global_payroll' \
--header 'Authorization: Bearer {{token}}'
```

Response:

```json focus={4,7-9,13-15}
{
  "data": [
    {
      "id": "gp8x3k5m",
      "title": "Senior Product Manager",
      "type": "global_payroll",
      "worker_first_name": "Maria",
      "worker_last_name": "Garcia",
      "status": "active",
      "employee": {
        "email": "maria.garcia@company.com",
        "employee_number": "EMP-2024-0042",
        "first_name": "Maria",
        "last_name": "Garcia"
      },
      "compensation_details": {
        "amount": 7500.00,
        "currency_code": "USD",
        "frequency": "monthly"
      }
    }
  ]
}
```

Save the `id` field - this is your `contract_id`.

### Retrieve available expense categories

Before creating a reimbursement, check which expense categories are available for your organization.

```shell
curl --request GET 'https://api.letsdeel.com/rest/adjustments/categories' \
--header 'Authorization: Bearer {{token}}'
```

Response:

```json focus={3-6,9-12}
{
  "data": [
    {
      "id": "c1a23456b78c90d1e2f3g4h5",
      "name": "Travel Expenses",
      "label": "Travel Expenses",
      "unit_type": "currency"
    },
    {
      "id": "c2b34567c89d01e3f4g5h6i7",
      "name": "Equipment Purchase",
      "label": "Equipment Purchase",
      "unit_type": "currency"
    },
    {
      "id": "c3c45678d90e12f4g5h6i7j8",
      "name": "Meals & Entertainment",
      "label": "Meals & Entertainment",
      "unit_type": "currency"
    }
  ]
}
```

Identify the category ID that matches your expense type. For this example, we will use the "Travel Expenses" category.

### Create the expense reimbursement

Submit the reimbursement with detailed description and expense breakdown. Include file attachments for receipts and invoices.

```shell
curl --request POST 'https://api.letsdeel.com/rest/adjustments' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "contract_id": "gp8x3k5m",
  "title": "Business Trip Reimbursement - NYC Client Meeting",
  "amount": "345.67",
  "adjustment_category_id": "c1a23456b78c90d1e2f3g4h5",
  "date_of_adjustment": "2026-02-10",
  "description": "Client meeting travel expenses: Flight $245.00, Hotel $85.67, Ground transport $15.00",
  "move_next_cycle": false,
  "file": {
    "id": "file_abc123xyz789",
    "name": "travel_receipts_feb2026.pdf",
    "fileType": "pdf"
  }
}'
```

> **Tip**
>
> Always provide a detailed description breaking down the expense. This helps with approval tracking,
> audit trails, and makes it clear to the employee what is being reimbursed.

Response:

```json focus={3-5,7-9}
{
  "data": {
    "id": "adj_9f8e7d6c-5b4a-3210-98fe-dcba09876543",
    "status": "OPEN",
    "created": true,
    "contract_id": "gp8x3k5m",
    "title": "Business Trip Reimbursement - NYC Client Meeting",
    "amount": "345.67",
    "adjustment_category_id": "c1a23456b78c90d1e2f3g4h5",
    "description": "Client meeting travel expenses: Flight $245.00, Hotel $85.67, Ground transport $15.00",
    "date_of_adjustment": "2026-02-10",
    "file": {
      "id": "file_abc123xyz789",
      "name": "travel_receipts_feb2026.pdf",
      "fileType": "pdf"
    },
    "created_at": "2026-02-06T14:30:00.000Z",
    "updated_at": "2026-02-06T14:30:00.000Z"
  }
}
```

The reimbursement is now created with `OPEN` status, ready for processing through the payroll cycle.

### Verify the reimbursement details

Confirm that the reimbursement was created correctly by retrieving its details.

```shell
curl --request GET 'https://api.letsdeel.com/rest/adjustments/adj_9f8e7d6c-5b4a-3210-98fe-dcba09876543' \
--header 'Authorization: Bearer {{token}}'
```

Response:

```json focus={4-5,8-9,16-20,24-27}
{
  "data": {
    "id": "adj_9f8e7d6c-5b4a-3210-98fe-dcba09876543",
    "status": "OPEN",
    "title": "Business Trip Reimbursement - NYC Client Meeting",
    "amount": "345.67",
    "contract_id": "gp8x3k5m",
    "adjustment_category_id": "c1a23456b78c90d1e2f3g4h5",
    "description": "Client meeting travel expenses: Flight $245.00, Hotel $85.67, Ground transport $15.00",
    "date_of_adjustment": "2026-02-10",
    "move_next_cycle": false,
    "cycle_reference": "2026-02",
    "actual_start_cycle_date": "2026-02-01T00:00:00.000Z",
    "actual_end_cycle_date": "2026-02-28T23:59:59.000Z",
    "file": {
      "id": "file_abc123xyz789",
      "name": "travel_receipts_feb2026.pdf",
      "fileType": "pdf"
    },
    "created_at": "2026-02-06T14:30:00.000Z",
    "updated_at": "2026-02-06T14:30:00.000Z"
  }
}
```

The reimbursement is associated with the correct payroll cycle and includes the attached receipt file.

### Track reimbursement status

As the reimbursement progresses through the payroll workflow, its status will change. Check the status periodically to track approval and payment.

```shell
curl --request GET 'https://api.letsdeel.com/rest/adjustments/adj_9f8e7d6c-5b4a-3210-98fe-dcba09876543' \
--header 'Authorization: Bearer {{token}}'
```

Response after approval:

```json focus={4}
{
  "data": {
    "id": "adj_9f8e7d6c-5b4a-3210-98fe-dcba09876543",
    "status": "SUCCESS",
    "title": "Business Trip Reimbursement - NYC Client Meeting",
    "amount": "345.67",
    "contract_id": "gp8x3k5m",
    "cycle_reference": "2026-02",
    "actual_start_cycle_date": "2026-02-01T00:00:00.000Z",
    "actual_end_cycle_date": "2026-02-28T23:59:59.000Z"
  }
}
```

Once the status changes to `SUCCESS`, the reimbursement has been approved and will be included in the employee's next payslip.

### Retrieve all reimbursements for an employee

To view the complete reimbursement history for an employee, list all adjustments for their contract.

```shell
curl --request GET 'https://api.letsdeel.com/rest/contracts/gp8x3k5m/adjustments' \
--header 'Authorization: Bearer {{token}}'
```

This returns all adjustments (bonuses, deductions, reimbursements) for the contract. Filter on the client side by category or description to identify expense reimbursements.

## Alternative: Manual approval workflow

For organizations requiring explicit approval before reimbursements are processed, use a manual approval workflow.

### Create reimbursement pending approval

Create the reimbursement in `DRAFT` status, requiring explicit approval before processing.

```shell
curl --request POST 'https://api.letsdeel.com/rest/adjustments' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "contract_id": "gp8x3k5m",
  "title": "Equipment Purchase - Monitor",
  "amount": "450.00",
  "adjustment_category_id": "c2b34567c89d01e3f4g5h6i7",
  "date_of_adjustment": "2026-02-10",
  "description": "Dell UltraSharp 27-inch monitor for home office setup",
  "file": {
    "id": "file_def456uvw012",
    "name": "monitor_receipt.pdf",
    "fileType": "pdf"
  }
}'
```

> **Note**
>
> Check with your payroll administrator about approval requirements. Some organizations require
> manager or finance approval for reimbursements above a certain threshold.

Response:

```json focus={4}
{
  "data": {
    "id": "adj_8g7f6e5d-4c3b-2109-87ed-cbaf98765432",
    "status": "DRAFT",
    "created": true,
    "title": "Equipment Purchase - Monitor",
    "amount": "450.00"
  }
}
```

The reimbursement is created in `DRAFT` status and will not be processed until explicitly approved.

> **Warning**
>
> Reimbursements in DRAFT status will not be included in payroll processing. Ensure timely approval
> to avoid payment delays for employees.

## Adding supporting documentation

For all expense reimbursements, attach receipts, invoices, or approval emails as supporting documentation.

### Upload and attach receipt file

Before creating the adjustment, upload the receipt file to your file storage and obtain the file ID.

```shell
# Example file upload (implementation depends on your file storage)
# After upload, you receive a file ID to reference in the adjustment

curl --request POST 'https://api.letsdeel.com/rest/adjustments' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "contract_id": "gp8x3k5m",
  "title": "Client Dinner Reimbursement",
  "amount": "187.50",
  "adjustment_category_id": "c3c45678d90e12f4g5h6i7j8",
  "date_of_adjustment": "2026-02-08",
  "description": "Client dinner at Bistro - 4 attendees, closed deal discussion",
  "file": {
    "id": "file_ghi789rst345",
    "name": "dinner_receipt_feb8.jpg",
    "fileType": "jpg"
  }
}'
```

The attached file will be available to approvers and linked to the adjustment for audit and compliance purposes.

> **Tip**
>
> Accepted file formats include PDF, JPG, PNG, and common document formats. Keep file sizes under
> 10MB for optimal processing.

## Common scenarios

### Scenario 1: Monthly mileage reimbursement

For employees who use personal vehicles for business, create monthly mileage reimbursements.

```shell
# Calculate: 450 miles × $0.67/mile = $301.50
curl --request POST 'https://api.letsdeel.com/rest/adjustments' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "contract_id": "gp8x3k5m",
  "title": "Mileage Reimbursement - January 2026",
  "amount": "301.50",
  "adjustment_category_id": "c1a23456b78c90d1e2f3g4h5",
  "date_of_adjustment": "2026-01-31",
  "description": "Business mileage for January 2026: 450 miles at $0.67/mile. Client visits and office meetings.",
  "file": {
    "id": "file_mileage_jan2026",
    "name": "mileage_log_january_2026.xlsx",
    "fileType": "xlsx"
  }
}'
```

> **Tip**
>
> For recurring monthly mileage reimbursements, standardize the title format and always attach a
> detailed mileage log showing dates, destinations, and business purposes.

### Scenario 2: Batch expense reimbursements

If you need to reimburse multiple employees for the same event (team offsite, conference), create separate adjustments for each employee.

```javascript
// Example: Batch processing conference expenses
const conferenceExpenses = [
  { contract_id: "gp8x3k5m", amount: "450.00", employee: "Maria Garcia" },
  { contract_id: "gp9y4l6n", amount: "450.00", employee: "James Chen" },
  { contract_id: "gp0z5m7o", amount: "475.00", employee: "Sarah Johnson" }
];

async function processBatchReimbursements(expenses) {
  const results = [];

  for (const expense of expenses) {
    const response = await fetch('https://api.letsdeel.com/rest/adjustments', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.DEEL_API_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        contract_id: expense.contract_id,
        title: "Tech Conference 2026 - Travel & Accommodation",
        amount: expense.amount.toString(),
        adjustment_category_id: "c1a23456b78c90d1e2f3g4h5",
        date_of_adjustment: "2026-02-15",
        description: "Annual tech conference attendance: Flight, hotel, meals"
      })
    });

    const data = await response.json();
    results.push({
      employee: expense.employee,
      adjustment_id: data.data.id,
      status: data.data.status
    });
  }

  return results;
}

// Process all reimbursements
processBatchReimbursements(conferenceExpenses)
  .then(results => console.log('Reimbursements created:', results))
  .catch(error => console.error('Error processing batch:', error));
```

### Scenario 3: Correcting reimbursement amounts

If you need to correct a reimbursement amount before it is processed, you can update the adjustment while it is still in `OPEN` or `DRAFT` status.

```shell
curl --request PATCH 'https://api.letsdeel.com/rest/adjustments/adj_9f8e7d6c-5b4a-3210-98fe-dcba09876543' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": "365.67",
  "description": "Client meeting travel expenses: Flight $245.00, Hotel $85.67, Ground transport $15.00, Parking $20.00 (updated)"
}'
```

> **Warning**
>
> You can only update adjustments in OPEN or DRAFT status. Once processed (SUCCESS status), you
> cannot modify the adjustment. If you need to correct a processed reimbursement, create a new
> adjustment with the difference amount.

### Scenario 4: Equipment purchase with multiple receipts

For large purchases with multiple receipts, combine all documentation into a single PDF before attaching.

```shell
curl --request POST 'https://api.letsdeel.com/rest/adjustments' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "contract_id": "gp8x3k5m",
  "title": "Home Office Setup - Complete Equipment",
  "amount": "1250.00",
  "adjustment_category_id": "c2b34567c89d01e3f4g5h6i7",
  "date_of_adjustment": "2026-02-05",
  "description": "Home office equipment: Standing desk $450, Ergonomic chair $350, Monitor $280, Keyboard & mouse $90, Desk lamp $80",
  "file": {
    "id": "file_equipment_bundle_2026",
    "name": "home_office_receipts_combined.pdf",
    "fileType": "pdf"
  }
}'
```

## Tracking expense reimbursements

### List reimbursements by date range

Track all reimbursements processed within a specific period for reporting and reconciliation.

```shell
curl --request GET 'https://api.letsdeel.com/rest/adjustments?start_date=2026-02-01&end_date=2026-02-28' \
--header 'Authorization: Bearer {{token}}'
```

Filter the response on the client side to identify expense reimbursements based on category or title patterns.

### List reimbursements by employee

Retrieve all adjustments for a specific contract to see the employee's complete reimbursement history.

```shell
curl --request GET 'https://api.letsdeel.com/rest/contracts/gp8x3k5m/adjustments' \
--header 'Authorization: Bearer {{token}}'
```

### Monitor pending reimbursements

Check which reimbursements are waiting for processing or approval.

```shell
curl --request GET 'https://api.letsdeel.com/rest/adjustments' \
--header 'Authorization: Bearer {{token}}'
```

Filter the response for adjustments with `OPEN`, `DRAFT`, or `PENDING_APPROVAL` status.

## Best practices

### Clear and detailed descriptions

Always include:

* The specific purpose of the expense (client meeting, equipment, travel)
* Itemized breakdown of costs when applicable
* Date or period the expense relates to
* Any relevant project, client, or event names

Good examples:

* "Client meeting travel - NYC: Flight $245, Hotel $85.67, Ground transport \$15"
* "Q1 2026 Monthly mileage: 450 miles at \$0.67/mile for client site visits"
* "Home office equipment: Standing desk $450, ergonomic chair $350"

Bad examples:

* "Travel expenses"
* "Reimbursement"
* "Equipment"

### Receipt documentation

* **Always attach receipts**: Include PDF or image files for all reimbursements
* **Combine multiple receipts**: For purchases with multiple items, combine into one PDF
* **Name files clearly**: Use descriptive filenames like `travel_receipts_feb2026.pdf`
* **Keep originals**: Store original receipts according to your organization's retention policy

### Timing and payroll cycles

* **Submit before cutoff**: Create reimbursements early in the payroll cycle
* **Check cycle dates**: Verify `actual_start_cycle_date` and `actual_end_cycle_date`
* **Allow processing time**: Submit at least 3-5 days before payroll cutoff
* **Track status**: Monitor status changes to ensure timely processing

### Expense categories

* **Use correct categories**: Match expense type to the appropriate category
* **Retrieve categories first**: Always call `/adjustments/categories` to get current options
* **Be consistent**: Use the same categories for similar expense types
* **Document mappings**: Keep an internal mapping of your expense types to Deel categories

### Approval workflows

* **Define thresholds**: Set clear approval thresholds (e.g., over \$500 requires manager approval)
* **Document policies**: Maintain clear expense reimbursement policies
* **Track approvers**: Know who is responsible for approving different expense types
* **Set deadlines**: Define approval turnaround times to avoid payment delays

### Compliance and audit

* **Maintain records**: Keep detailed records of all reimbursements
* **Include business purpose**: Always document why the expense was incurred
* **Attach approvals**: Include manager approval emails when applicable
* **Follow tax rules**: Be aware of taxable vs non-taxable reimbursements in your jurisdiction

## Troubleshooting

#### Reimbursement not appearing on payslip

Check that the reimbursement status is SUCCESS and that it was submitted before the payroll
cutoff date. If the payroll cycle has already closed, the reimbursement will appear on the next
payslip. Verify the cycle\_reference matches the expected payroll period.

#### Cannot update reimbursement amount

Reimbursements can only be updated while in OPEN or DRAFT status. Once processed (SUCCESS
status), they cannot be modified. If you need to correct a processed reimbursement, create a new
adjustment for the difference amount with a clear description explaining the correction.

#### File attachment failed

Ensure the file ID is valid and the file was successfully uploaded to your file storage before
creating the adjustment. Check that file size is under 10MB and the file format is supported
(PDF, JPG, PNG, XLSX, DOCX). If the file field is optional for your use case, you can submit
the reimbursement without an attachment and add it later.

#### Wrong expense category selected

If you used the wrong category and the reimbursement is still in OPEN or DRAFT status, update
the adjustment with the correct adjustment\_category\_id. If already processed, contact your
payroll administrator for assistance with reclassification.

#### Reimbursement rejected or failed

Check the adjustment status for error details. Common causes include invalid contract\_id,
payroll cycle already closed, insufficient information in description, or missing required
documentation. Review the error message and resubmit with corrections. Status FAILED indicates a
processing error; create a new adjustment with corrected information.

#### Employee did not receive reimbursement notification

Notifications are typically sent when payroll is processed, not when the adjustment is created.
Check that the adjustment status is SUCCESS and the payroll cycle has been processed. If the
employee questions the reimbursement, provide the adjustment ID and confirm it appears on their
payslip.

## Next steps

#### [Adjustments](/api/global-payroll/adjustments)

Learn about other adjustment types including bonuses and deductions

#### [Webhooks](/api/webhooks/introduction)

Set up webhooks to monitor adjustment status changes automatically

#### [Authentication](/api/authentication)

Learn how to authenticate API requests and manage tokens

#### [Time Tracking](/api/global-payroll/time-tracking)

Learn how to submit shifts and hours for payroll calculation