Invoice adjustments | Deel

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

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

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

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

$ 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
>   }
> }'

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.

$ 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:

1 {
2   "data": {
3     "id": "adj-9876543210",
4     "status": "pending",
5     "created": true,
6     "created_at": "2026-01-27T10:15:00Z",
7     "type": "bonus",
8     "amount": 500.00,
9     "description": "Q4 performance bonus for exceeding project targets"
10   }
11 }

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.

$ 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"
>   }
> }'

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

Decline an adjustment

$ 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"
>   }
> }'

Update an adjustment

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

Request

$ 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"
>   }
> }'

Delete an adjustment

Request

Response format

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

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

Retrieve adjustments

Get a specific adjustment

Retrieve detailed information about a single adjustment by its ID.

Request

Response

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

List all adjustments

Retrieve a list of all adjustments with optional filtering.

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

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

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

Create the adjustment

$ 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:

1 {
2   "data": {
3     "id": "adj-abc123",
4     "status": "pending",
5     "created": true,
6     "created_at": "2026-01-27T10:15:00Z"
7   }
8 }

Retrieve adjustment details

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

Response:

1 {
2   "data": {
3     "id": "adj-abc123",
4     "type": "bonus",
5     "status": "pending",
6     "total_amount": "1000.00",
7     "currency_code": "USD",
8     "description": "Project completion bonus - delivered 2 weeks ahead of schedule",
9     "contract": {
10       "id": "c1234567-89ab-4def-0123-456789abcdef",
11       "type": "ongoing_time_based",
12       "title": "Senior Backend Engineer Contract"
13     }
14   }
15 }

Review and approve

$ 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:

1 {
2   "data": {
3     "created": true
4   }
5 }

Verify approval

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

Response:

1 {
2   "data": {
3     "id": "adj-abc123",
4     "status": "approved",
5     "type": "bonus",
6     "total_amount": "1000.00",
7     "reported_by": {
8       "id": "worker_123456",
9       "full_name": "John Doe"
10     },
11     "reviewed_by": {
12       "id": "reviewer_78910",
13       "full_name": "Jane Smith",
14       "reviewed_at": "2026-01-27T15:30:00Z",
15       "remarks": "Project milestone verified - bonus approved per contract terms"
16     }
17   }
18 }

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.