***

title: Give bonus to contractors
subtitle: Step-by-step guide to adding bonus payments to contractor invoices
max-toc-depth: 2
----------------

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

## Step-by-step workflow

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

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

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

  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/v2/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/v2/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.
</Steps>

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

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

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

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

## 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/v2/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/v2/invoice-adjustments?types=bonus&statuses=pending' \
--header 'Authorization: Bearer {{token}}'

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

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

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

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

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

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

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

## Next steps

* Review the complete [invoice adjustments documentation](/api/contractors/invoice-adjustments) for other adjustment types
* Learn about [off-cycle payments](/api/reference/endpoints/invoicing/create-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