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

# Give bonus to contractors

## Overview

This guide walks you through the complete process of paying a bonus to a contractor using the invoice adjustments API. You will learn how to create, review, and track a bonus payment from start to finish.

## When to use this workflow

Use this workflow when you need to:

* Reward contractors for exceptional performance
* Pay project completion bonuses
* Add end-of-year or holiday bonuses
* Include sales or performance-based incentives
* Compensate for work delivered ahead of schedule

## Prerequisites

Before you begin, ensure you have:

* A valid API token with `invoice-adjustments:write` scope
* The `contract_id` of the contractor receiving the bonus
* The bonus amount and reason for payment

> **Note**
>
> Bonus payments are tied to payment cycles. Make sure the contract has an active payment cycle
> when creating the adjustment.

## Step-by-step workflow

This example demonstrates paying a \$1,500 performance bonus to a contractor who exceeded quarterly targets.

### Identify the contract

First, retrieve the contract ID if you don't already have it. You can list contracts and filter by worker email or external ID.

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

Response:

```json focus={4,7-8}
{
  "data": [
    {
      "id": "c3f9a1d2",
      "title": "Senior Backend Engineer",
      "type": "ongoing_time_based",
      "worker_first_name": "John",
      "worker_last_name": "Doe",
      "status": "active",
      "compensation_details": {
        "amount": 8000.00,
        "currency_code": "USD",
        "frequency": "monthly"
      }
    }
  ]
}
```

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

### Create the bonus adjustment

Create the bonus adjustment with a clear description explaining why the bonus is being paid.

```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": 1500.00,
    "contract_id": "c3f9a1d2",
    "description": "Q4 2025 performance bonus - exceeded sales targets by 140%",
    "date_submitted": "2026-01-27"
  }
}'
```

> **Tip**
>
> Always include specific details in the description. This helps with approval tracking and
> provides context for the contractor and finance teams.

Response:

```json focus={3-5}
{
  "data": {
    "id": "1a0aa359-ef15-4a47-9629-bcf36addbe41",
    "status": "pending",
    "created": true,
    "created_at": "2026-01-27T10:15:00Z"
  }
}
```

The adjustment is now created with a `pending` status, waiting for review and approval.

### Verify the adjustment

Check that the adjustment was created correctly by retrieving its details.

```shell
curl --request GET 'https://api.letsdeel.com/rest/invoice-adjustments/1a0aa359-ef15-4a47-9629-bcf36addbe41' \
--header 'Authorization: Bearer {{token}}'
```

Response:

```json focus={4-5,9,14-17}
{
  "data": {
    "id": "1a0aa359-ef15-4a47-9629-bcf36addbe41",
    "type": "bonus",
    "status": "pending",
    "contract": {
      "id": "c3f9a1d2",
      "type": "ongoing_time_based",
      "title": "Senior Backend Engineer Contract"
    },
    "total_amount": "1500.00",
    "currency_code": "USD",
    "description": "Q4 2025 performance bonus - exceeded sales targets by 140%",
    "created_at": "2026-01-27T10:15:00Z",
    "date_submitted": "2026-01-27",
    "reported_by": {
      "id": "user_456789",
      "full_name": "Sarah Johnson"
    },
    "payment_cycle": {
      "start_date": "2026-01-01T00:00:00Z",
      "end_date": "2026-01-31T23:59:59Z"
    }
  }
}
```

The adjustment is associated with the correct contract and payment cycle.

### Approve the bonus

Review and approve the bonus adjustment. This step moves it from `pending` to `approved` status.

```shell
curl --request POST 'https://api.letsdeel.com/rest/invoice-adjustments/1a0aa359-ef15-4a47-9629-bcf36addbe41/reviews' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "status": "approved",
    "reason": "Performance verified by team lead. Bonus approved per Q4 incentive program."
  }
}'
```

> **Note**
>
> The `reason` field is optional but recommended. It creates an audit trail and helps explain
> approval decisions.

Response:

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

### Confirm approval status

Retrieve the adjustment again to confirm it has been approved.

```shell
curl --request GET 'https://api.letsdeel.com/rest/invoice-adjustments/1a0aa359-ef15-4a47-9629-bcf36addbe41' \
--header 'Authorization: Bearer {{token}}'
```

Response:

```json focus={4,18-22}
{
  "data": {
    "id": "1a0aa359-ef15-4a47-9629-bcf36addbe41",
    "status": "approved",
    "type": "bonus",
    "total_amount": "1500.00",
    "currency_code": "USD",
    "description": "Q4 2025 performance bonus - exceeded sales targets by 140%",
    "contract": {
      "id": "c3f9a1d2",
      "title": "Senior Backend Engineer Contract"
    },
    "reported_by": {
      "id": "user_456789",
      "full_name": "Sarah Johnson"
    },
    "reviewed_by": {
      "id": "reviewer_123456",
      "full_name": "Mike Chen",
      "reviewed_at": "2026-01-27T15:30:00Z",
      "remarks": "Performance verified by team lead. Bonus approved per Q4 incentive program."
    },
    "payment_cycle": {
      "start_date": "2026-01-01T00:00:00Z",
      "end_date": "2026-01-31T23:59:59Z"
    }
  }
}
```

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

### Monitor payment status

The approved bonus will appear on the contractor's next invoice. You can track when it is paid by checking the adjustment status.

```shell
curl --request GET 'https://api.letsdeel.com/rest/invoice-adjustments/1a0aa359-ef15-4a47-9629-bcf36addbe41' \
--header 'Authorization: Bearer {{token}}'
```

Once the invoice is paid, the status will change to `paid`:

```json focus={4,18}
{
  "data": {
    "id": "1a0aa359-ef15-4a47-9629-bcf36addbe41",
    "status": "paid",
    "type": "bonus",
    "total_amount": "1500.00",
    "currency_code": "USD",
    "invoice_id": "inv-987654321",
    "payment_cycle": {
      "start_date": "2026-01-01T00:00:00Z",
      "end_date": "2026-01-31T23:59:59Z"
    }
  }
}
```

The `invoice_id` field now contains the ID of the paid invoice that includes this bonus.

## Alternative: Auto-approved bonus

For pre-authorized bonuses or recurring bonus programs, you can skip the manual approval step by using auto-approval.

### Create and auto-approve in one step

```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": "Standard monthly performance bonus - contractually agreed",
    "date_submitted": "2026-01-27",
    "is_auto_approved": true
  }
}'
```

Response:

```json focus={4}
{
  "data": {
    "id": "1a0aa359-ef15-4a47-9629-bcf36addbe41",
    "status": "approved",
    "created": true,
    "created_at": "2026-01-27T10:15:00Z"
  }
}
```

The adjustment is created with `approved` status immediately, bypassing the manual review workflow.

> **Warning**
>
> Only use auto-approval for bonuses that have already been authorized or are part of a standard
> program. Manual review provides an important control point for ad-hoc or large bonus payments.

## Adding supporting documentation

For bonuses based on performance metrics or contract terms, attach supporting documentation.

### Create bonus with performance report

```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": 2000.00,
    "contract_id": "c1234567",
    "description": "Project completion bonus - delivered MVP 3 weeks ahead of schedule",
    "date_submitted": "2026-01-27",
    "attachment": {
      "key": "invoice_adjustment_attachments/2026/01/project_completion_report.pdf",
      "filename": "project_completion_report.pdf"
    }
  }
}'
```

The attached document will be available to reviewers and will be linked to the adjustment for audit purposes.

## Handling recurring bonuses

For bonuses that repeat every payment cycle, such as monthly sales commissions or standard performance incentives, use recurring adjustments.

### Create recurring monthly bonus

```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": "bonus",
    "amount": 750.00,
    "contract_id": "c1234567",
    "description": "Monthly sales commission - 5% of monthly sales target achievement",
    "date_submitted": "2026-01-27"
  }
}'
```

This creates a recurring rule that automatically generates a new bonus adjustment for each payment cycle.

> **Note**
>
> Recurring adjustments continue until you delete them. Each cycle creates a new adjustment with a
> unique ID that can be reviewed independently.

### Stop recurring bonus

When the recurring bonus is no longer needed, delete the original adjustment to stop future occurrences.

```shell
curl --request DELETE 'https://api.letsdeel.com/rest/invoice-adjustments/1a0aa359-ef15-4a47-9629-bcf36addbe41' \
--header 'Authorization: Bearer {{token}}'
```

## Common scenarios

### Scenario 1: Year-end bonus for all contractors

If you need to pay bonuses to multiple contractors, create separate adjustments for each contract.

```shell
# Contractor 1
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": "contract-id-1",
    "description": "2025 Year-end performance bonus",
    "date_submitted": "2026-01-27"
  }
}'

# Contractor 2
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": 1200.00,
    "contract_id": "contract-id-2",
    "description": "2025 Year-end performance bonus",
    "date_submitted": "2026-01-27"
  }
}'
```

> **Tip**
>
> Automate this process by iterating through your contractor list and creating adjustments
> programmatically. Use batch processing to handle large numbers of contractors efficiently.

### Scenario 2: Tiered performance bonus

For bonuses based on performance tiers, calculate the amount before creating the adjustment.

```javascript
// Example: Calculate tiered bonus
const performanceScore = 142; // 142% of target
let bonusAmount = 0;

if (performanceScore >= 150) {
  bonusAmount = 2000;
} else if (performanceScore >= 125) {
  bonusAmount = 1500;
} else if (performanceScore >= 100) {
  bonusAmount = 1000;
}

// Create adjustment with calculated amount
const adjustment = {
  type: "bonus",
  amount: bonusAmount,
  contract_id: "c1234567",
  description: `Q4 performance bonus - achieved ${performanceScore}% of target`,
  date_submitted: "2026-01-27"
};
```

### Scenario 3: Correcting a bonus amount

If you need to correct a bonus amount before it is paid, update the pending adjustment.

```shell
curl --request PATCH 'https://api.letsdeel.com/rest/invoice-adjustments/1a0aa359-ef15-4a47-9629-bcf36addbe41' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "amount": 1750.00,
    "description": "Q4 2025 performance bonus - exceeded sales targets by 140% (corrected amount)"
  }
}'
```

> **Warning**
>
> You can only update adjustments in `pending` status. Once approved or paid, adjustments cannot
> be modified. If you need to correct an approved adjustment, create a new adjustment with the
> difference amount.

## Tracking bonus payments

### List all bonuses for a contractor

Retrieve all bonus adjustments for a specific contract to track historical payments.

```shell
curl --request GET 'https://api.letsdeel.com/rest/contracts/c1234567-89ab-4def-0123-456789abcdef/invoice-adjustments?types=bonus' \
--header 'Authorization: Bearer {{token}}'
```

### List bonuses by status

Filter bonuses by status to see what is pending approval or already paid.

```shell
# Pending bonuses
curl --request GET 'https://api.letsdeel.com/rest/invoice-adjustments?types=bonus&statuses=pending' \
--header 'Authorization: Bearer {{token}}'

# Approved bonuses waiting for payment
curl --request GET 'https://api.letsdeel.com/rest/invoice-adjustments?types=bonus&statuses=approved' \
--header 'Authorization: Bearer {{token}}'

# Paid bonuses
curl --request GET 'https://api.letsdeel.com/rest/invoice-adjustments?types=bonus&statuses=paid' \
--header 'Authorization: Bearer {{token}}'
```

### List bonuses by date range

Track bonuses paid within a specific time period for reporting purposes.

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

## Best practices

### Clear descriptions

Always include:

* The reason for the bonus (performance, completion, sales, etc.)
* The time period or achievement being rewarded
* Any relevant metrics or benchmarks met

Good examples:

* "Q4 2025 performance bonus - exceeded sales targets by 140%"
* "Project completion bonus - delivered MVP 3 weeks ahead of schedule"
* "Annual loyalty bonus - 2 years of exceptional service"

Bad examples:

* "Bonus"
* "Extra payment"
* "Additional compensation"

### Timing considerations

* Create bonuses early in the payment cycle to ensure they appear on the current invoice
* Late submissions may roll over to the next payment cycle
* Check payment cycle dates before creating adjustments

### Documentation

* Attach performance reports, project completion documents, or contract references
* Keep records of approval decisions for compliance and audit purposes
* Document the bonus calculation methodology for recurring programs

### Approval workflow

* Use manual approval for one-time or large bonuses
* Use auto-approval only for pre-authorized standard bonuses
* Assign appropriate reviewers with authority to approve bonus payments
* Include clear approval reasons for audit trails

## Troubleshooting

#### Bonus not appearing on the invoice

Check that the bonus is approved and that the payment cycle includes the submission date. If
the invoice has already been generated, the bonus will appear on the next invoice.

#### Cannot update bonus amount

Bonuses can only be updated while in `pending` status. If already approved, you must create a
new adjustment for the difference amount or decline the original and create a new one.

#### Recurring bonus creating duplicate payments

Each recurring cycle creates a new adjustment. If you see duplicates, check if multiple
recurring rules were created. Delete extra rules to stop duplicate generation.

#### Bonus paid in wrong currency

Bonuses use the contract currency and cannot be changed. If you need to pay in a different
currency, use off-cycle payments instead of invoice adjustments.

#### Contractor did not receive bonus notification

Notifications are sent when the invoice is generated, not when the adjustment is created.
Check the invoice generation date and ensure the adjustment was approved before that date.

## Next steps

* Review the complete [invoice adjustments documentation](/api/contractors/invoice-adjustments) for other adjustment types
* Learn about [off-cycle payments](/api/reference/endpoints/off-cycle/create-contract-off-cycle-payment) for immediate payments outside the regular cycle
* Set up [webhooks](/api/webhooks/introduction) to monitor adjustment status changes automatically
* Explore [contractor contract creation](/api/contractors/creating-contracts) to understand payment structures