***

title: Invoice adjustments
subtitle: 'Add, update, and manage line items on contractor invoices'
---------------------------------------------------------------------

## 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.
</Note>

## 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.
</Warning>

## 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/v2/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/v2/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.
</Tip>

### 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/v2/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/v2/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.
</Note>

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

<Tabs>
  <Tab title="Approve an adjustment">
    ```shell
    curl --request POST 'https://api.letsdeel.com/rest/v2/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"
      }
    }'
    ```
  </Tab>

  <Tab title="Decline an adjustment">
    ```shell
    curl --request POST 'https://api.letsdeel.com/rest/v2/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.
    </Warning>
  </Tab>
</Tabs>

## Update an adjustment

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

<Tabs>
  <Tab title="Request">
    ```shell
    curl --request PATCH 'https://api.letsdeel.com/rest/v2/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"
      }
    }'
    ```
  </Tab>

  <Tab title="Request">
    ```json
    {
      "data": {
        "updated": true
      }
    }
    ```
  </Tab>
</Tabs>

## Delete an adjustment

<Tabs>
  <Tab title="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/v2/invoice-adjustments/{{adjustment_id}}' \
    --header 'Authorization: Bearer {{token}}'
    ```
  </Tab>

  <Tab title="Response format">
    ```json
    {
      "data": {
        "deleted": true
      }
    }
    ```
  </Tab>
</Tabs>

## Retrieve adjustments

### Get a specific adjustment

Retrieve detailed information about a single adjustment by its ID.

<Tabs>
  <Tab title="Request">
    ```shell
    curl --request GET 'https://api.letsdeel.com/rest/v2/invoice-adjustments/{{adjustment_id}}' \
    --header 'Authorization: Bearer {{token}}'
    ```
  </Tab>

  <Tab title="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"
          }
        }
      }
    ```
  </Tab>
</Tabs>

### List all adjustments

Retrieve a list of all adjustments with optional filtering.

```shell
curl --request GET 'https://api.letsdeel.com/rest/v2/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/v2/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/v2/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.

<Steps>
  ### Create the adjustment

  ```shell
  curl --request POST 'https://api.letsdeel.com/rest/v2/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/v2/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/v2/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/v2/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.
</Steps>

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>