> This page is for API, version 2026-01-01 (Stable) (default).
> For other versions, use one of these documentation indexes:
> - 2026-01-01 (Stable) (default): https://developer.deel.com/api/stable/llms.txt

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

# Invoice adjustments

## Overview

Invoice adjustments let you modify contractor invoices by adding or updating line items for specific payment cycles. Use adjustments to add bonuses, commissions, reimbursements, deductions, or other custom charges that reflect actual work delivered.

Adjustments ensure invoices remain accurate and compliant without manual edits. Each adjustment is tracked, versioned, and subject to an approval workflow before being applied to the final invoice.

## Common use cases

Invoice adjustments solve real-world invoicing needs:

* **Performance bonuses**: Reward contractors for exceeding targets or completing projects ahead of schedule.
* **Expense reimbursements**: Add documented expenses like travel costs, equipment purchases, or software subscriptions.
* **Deductions**: Apply penalties for late delivery, quality issues, or contractual violations.
* **Commissions**: Include variable pay based on sales performance or project outcomes.
* **Tax adjustments**: Modify VAT or withholding tax percentages based on local requirements.
* **Corrections**: Fix errors in previously submitted invoices or timesheets.

## Understanding adjustment types

Each adjustment has a `type` that determines how it appears on the invoice and how it affects the total amount.

### Available adjustment types

| Type              | Description                                                    | Effect on Total |
| ----------------- | -------------------------------------------------------------- | --------------- |
| `bonus`           | One-time or recurring performance bonus                        | Increases       |
| `commission`      | Sales or project-based commission payment                      | Increases       |
| `reimbursement`   | Expense reimbursement for contractor-paid costs                | Increases       |
| `deduction`       | Penalty or correction that reduces the invoice amount          | Decreases       |
| `accrued_holiday` | Holiday pay adjustment for contracts that accrue time off      | Increases       |
| `overtime`        | Additional pay for hours worked beyond standard contract terms | Increases       |
| `custom`          | Other adjustment types not covered by standard categories      | Varies          |

> **Note**
>
> The `type` field is required when creating an adjustment. Choose the type that best represents
> the nature of the adjustment for accurate reporting and compliance tracking.

## Adjustment statuses

Adjustments move through a lifecycle with distinct statuses:

| Status     | Description                                                 | Actions Available      |
| ---------- | ----------------------------------------------------------- | ---------------------- |
| `pending`  | Submitted and awaiting review                               | Update, Delete, Review |
| `approved` | Reviewed and approved. Will be included in the next invoice | View only              |
| `declined` | Reviewed and rejected. Will not be included in the invoice  | View only              |
| `paid`     | Included in a paid invoice. Cannot be modified              | View only              |

> **Warning**
>
> Once an adjustment is marked as `paid`, it cannot be modified or deleted. Always review
> adjustments carefully before approval.

## Create an adjustment

Creating an adjustment requires three key pieces of information: the contract ID, the adjustment type, and the amount.

### Basic adjustment

```shell
curl --request POST 'https://api.letsdeel.com/rest/invoice-adjustments' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "type": "bonus",
    "amount": 500.00,
    "contract_id": "c1234567-89ab-4def-0123-456789abcdef",
    "description": "Q4 performance bonus for exceeding project targets",
    "date_submitted": "2026-01-27"
  }
}'
```

### Adjustment with auto-approval

You can automatically approve an adjustment at creation time by setting `is_auto_approved: true`. This bypasses the review workflow and immediately includes the adjustment in the next invoice.

```shell
curl --request POST 'https://api.letsdeel.com/rest/invoice-adjustments' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "type": "reimbursement",
    "amount": 150.00,
    "contract_id": "c1234567-89ab-4def-0123-456789abcdef",
    "description": "Travel expenses for client meeting",
    "date_submitted": "2026-01-27",
    "is_auto_approved": true
  }
}'
```

> **Tip**
>
> Use auto-approval for pre-authorized adjustments like standard expense reimbursements or
> contractually agreed bonuses to streamline your workflow.

### Adjustment with attachment

Include supporting documentation by attaching files to adjustments. This is particularly useful for expense reimbursements, invoices, or receipts.

```shell
curl --request POST 'https://api.letsdeel.com/rest/invoice-adjustments' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "type": "reimbursement",
    "amount": 350.00,
    "contract_id": "c1234567-89ab-4def-0123-456789abcdef",
    "description": "Equipment purchase - noise-canceling headphones",
    "date_submitted": "2026-01-27",
    "attachment": {
      "key": "invoice_adjustment_attachments/2026/01/receipt_12345.pdf",
      "filename": "equipment_receipt.pdf"
    }
  }
}'
```

### Response format

All adjustment creation requests return a consistent response format:

```json
{
  "data": {
    "id": "adj-9876543210",
    "status": "pending",
    "created": true,
    "created_at": "2026-01-27T10:15:00Z",
    "type": "bonus",
    "amount": 500.00,
    "description": "Q4 performance bonus for exceeding project targets"
  }
}
```

## Recurring adjustments

For adjustments that repeat every payment cycle, use the `recurring` query parameter. This is useful for ongoing commissions, monthly stipends, or regular deductions.

```shell
curl --request POST 'https://api.letsdeel.com/rest/invoice-adjustments?recurring=true' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "type": "commission",
    "amount": 250.00,
    "contract_id": "c1234567-89ab-4def-0123-456789abcdef",
    "description": "Monthly sales commission",
    "date_submitted": "2026-01-27"
  }
}'
```

> **Note**
>
> Recurring adjustments are automatically created for each new payment cycle until you delete the
> recurring rule. Each cycle creates a new adjustment with a unique ID.

## Review and approve adjustments

Adjustments in `pending` status require review before they are included in invoices. Use the review endpoint to approve or decline adjustments.

#### Approve an adjustment

```shell
curl --request POST 'https://api.letsdeel.com/rest/invoice-adjustments/{{adjustment_id}}/reviews' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "status": "approved",
    "reason": "Invoice amount verified and matches contract terms"
  }
}'
```

#### Decline an adjustment

```shell
curl --request POST 'https://api.letsdeel.com/rest/invoice-adjustments/{{adjustment_id}}/reviews' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "status": "declined",
    "reason": "Supporting documentation not provided"
  }
}'
```

> **Warning**
>
> Always provide a clear reason when declining adjustments. This helps contractors understand why
> their adjustment was rejected and what they need to provide for resubmission.

## Update an adjustment

You can update pending adjustments before they are approved. Once approved or paid, adjustments cannot be modified.

#### Request

```shell
curl --request PATCH 'https://api.letsdeel.com/rest/invoice-adjustments/{{adjustment_id}}' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "title": "Updated Year-End Bonus",
    "amount": 600.00,
    "description": "Adjusted bonus amount after final performance review"
  }
}'
```

#### Request

```json
{
  "data": {
    "updated": true
  }
}
```

## Delete an adjustment

#### Request

Remove pending adjustments that are no longer needed. Approved or paid adjustments cannot be deleted.

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

#### Response format

```json
{
  "data": {
    "deleted": true
  }
}
```

## Retrieve adjustments

### Get a specific adjustment

Retrieve detailed information about a single adjustment by its ID.

#### Request

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

#### Response

```json
  {
    "data": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "bonus",
      "status": "approved",
      "contract": {
        "id": "c1a2b3d4-e5f6-7890-abcd-1234567890ef",
        "type": "ongoing_time_based",
        "title": "Senior Software Engineer Contract"
      },
      "total_amount": "500.00",
      "currency_code": "USD",
      "description": "Q4 performance bonus for exceeding project targets",
      "created_at": "2026-01-15T09:30:00Z",
      "date_submitted": "2026-01-15T09:30:00Z",
      "reported_by": {
        "id": "worker_123456",
        "full_name": "John Doe"
      },
      "reviewed_by": {
        "id": "reviewer_78910",
        "full_name": "Jane Smith",
        "reviewed_at": "2026-01-20T14:45:00Z",
        "remarks": "Verified and approved for payment"
      },
      "payment_cycle": {
        "start_date": "2026-01-01T00:00:00Z",
        "end_date": "2026-01-31T23:59:59Z"
      }
    }
  }
```

### List all adjustments

Retrieve a list of all adjustments with optional filtering.

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

### Filter adjustments

You can filter the list by contract, type, status, or date range.

```shell
curl --request GET 'https://api.letsdeel.com/rest/invoice-adjustments?contract_id=c1234567&types=bonus,commission&statuses=approved&start_date=2026-01-01&end_date=2026-01-31' \
--header 'Authorization: Bearer {{token}}'
```

### Available filters

| Filter Parameter | Description                                            | Example              |
| ---------------- | ------------------------------------------------------ | -------------------- |
| `contract_id`    | Filter by specific contract ID                         | `c1234567-89ab-4def` |
| `types`          | Filter by adjustment types (comma-separated)           | `bonus,commission`   |
| `statuses`       | Filter by adjustment statuses (comma-separated)        | `pending,approved`   |
| `start_date`     | Get adjustments submitted on or after this date        | `2026-01-01`         |
| `end_date`       | Get adjustments submitted before this date (exclusive) | `2026-01-31`         |
| `contract_types` | Filter by contract type                                | `ongoing_time_based` |

### Get adjustments for a specific contract

Retrieve all adjustments for a specific contract.

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

This endpoint accepts the same filtering parameters as the global list endpoint.

## Best practices

### Provide clear descriptions

Always include a detailed description that explains:

* What the adjustment is for
* Why it is being applied
* Any relevant context or reference numbers

Good descriptions improve transparency and reduce approval delays.

### Attach supporting documentation

For reimbursements and deductions, always attach supporting documentation:

* Receipts for expense reimbursements
* Performance reports for bonuses
* Time logs for overtime adjustments
* Contractual references for deductions

### Use appropriate adjustment types

Choose the correct adjustment type to ensure accurate reporting and compliance tracking. Avoid using `custom` when a standard type applies.

### Review before approval

Verify all adjustment details before approving:

* Amount matches supporting documentation
* Description is clear and accurate
* Correct contract and payment cycle
* Attachment is readable and relevant

### Leverage auto-approval for standard adjustments

For pre-authorized adjustments with fixed amounts, use auto-approval to streamline processing:

* Standard expense allowances
* Contractually agreed bonuses
* Regular monthly commissions

### Monitor recurring adjustments

Regularly review recurring adjustments to ensure they are still needed. Delete recurring rules when they are no longer applicable to prevent incorrect charges.

## Complete workflow example

This example demonstrates the complete adjustment lifecycle from creation to approval.

### Create the adjustment

```shell
curl --request POST 'https://api.letsdeel.com/rest/invoice-adjustments' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "type": "bonus",
    "amount": 1000.00,
    "contract_id": "c1234567-89ab-4def-0123-456789abcdef",
    "description": "Project completion bonus - delivered 2 weeks ahead of schedule",
    "date_submitted": "2026-01-27"
  }
}'
```

Response:

```json
{
  "data": {
    "id": "adj-abc123",
    "status": "pending",
    "created": true,
    "created_at": "2026-01-27T10:15:00Z"
  }
}
```

### Retrieve adjustment details

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

Response:

```json
{
  "data": {
    "id": "adj-abc123",
    "type": "bonus",
    "status": "pending",
    "total_amount": "1000.00",
    "currency_code": "USD",
    "description": "Project completion bonus - delivered 2 weeks ahead of schedule",
    "contract": {
      "id": "c1234567-89ab-4def-0123-456789abcdef",
      "type": "ongoing_time_based",
      "title": "Senior Backend Engineer Contract"
    }
  }
}
```

### Review and approve

```shell
curl --request POST 'https://api.letsdeel.com/rest/invoice-adjustments/adj-abc123/reviews' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "status": "approved",
    "reason": "Project milestone verified - bonus approved per contract terms"
  }
}'
```

Response:

```json
{
  "data": {
    "created": true
  }
}
```

### Verify approval

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

Response:

```json focus={4,12-16}
{
  "data": {
    "id": "adj-abc123",
    "status": "approved",
    "type": "bonus",
    "total_amount": "1000.00",
    "reported_by": {
      "id": "worker_123456",
      "full_name": "John Doe"
    },
    "reviewed_by": {
      "id": "reviewer_78910",
      "full_name": "Jane Smith",
      "reviewed_at": "2026-01-27T15:30:00Z",
      "remarks": "Project milestone verified - bonus approved per contract terms"
    }
  }
}
```

The adjustment is now approved and will be included in the next invoice for this payment cycle.

## FAQ

#### What happens if I delete a recurring adjustment?

Deleting a recurring adjustment only removes the recurring rule. Adjustments that have already
been created for past cycles will remain, but no new adjustments will be created for future
cycles.

#### Can I modify an approved adjustment?

No. Once an adjustment is approved, it cannot be modified or deleted. If you need to make
changes, you must create a new adjustment with the correct values and decline the original one.

#### How do adjustments affect contractor payments?

Approved adjustments are added to the contractor's invoice for the specified payment cycle.
The total invoice amount is calculated by adding all approved adjustments to the base contract
amount, timesheets, and other line items.

#### Can I attach multiple files to an adjustment?

Currently, each adjustment supports one attachment. If you need to include multiple documents,
combine them into a single PDF file before uploading.

#### What currencies are supported for adjustments?

Adjustments use the same currency as the contract they are associated with. The currency is
automatically inherited from the contract and cannot be changed at the adjustment level.

#### How long does it take for an approved adjustment to appear on the invoice?

Approved adjustments appear on the next invoice generated for the specified payment cycle. If
the invoice has already been generated, the adjustment will be included in the following
invoice.