v1

latestOpenAPI 3.1.02026-07-242735131.1 MB

Incentives

Update Incentive

Updates an Incentive.

Incentives use the currency of the employment specified provided in the employment_id field.

The API doesn't support updating paid incentives.

Scopes

Category	Read only Scope	Write only Scope (read access implicit)
Manage expenses (employment_payments)	-	Manage incentives (incentive:write)

put/v1/incentives/{id}

Path parameters

idstring required

Incentive ID

Headers

Authorizationstring required

Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.

The refresh token needs to have been obtained through the Authorization Code flow.

Request body

amountinteger

The amount (in the currency of the employment) to be given to the employee.

This field accepts fractional amounts as well. However to avoid precision issues and errors that can arise from storing fractional amounts, the Remote API only accepts currencies and their fractional amounts as integers. This means you should append fractional amounts to the end of the amount you're passing in with this field.

For example, if the incentive you're offering is EUR 500.25, you would specify 50025 as the amount for this field.

amount_tax_type'gross' | 'net'

Whether the amount given accounts for taxes or not.

gross indicates that the amount given is the amount to be paid before taxes are subtracted.

net indicates that the amount given is the amount which will be paid to the employee after taxes. Remote will gross this up to ensure the taxes are included and employee receives the amount requested without further reduction.

effective_datestring date

The date at which the incentive should take effect.

Note that the incentive is not paid out on the effective date, but during the next payroll cycle. The effective date determines which payroll cycle the incentive will be paid out in.

The effective date needs to be today or a future date.

Note for recurring incentives: since the months don't have the same amount of days, if day of month of effective_date is one of [28, 29, 30, 31] it will be transformed to the last day of each month, avoiding the possibility of skipping a month in the recurrence.

notestring nullable

period_endstring date nullable

The end date of the incentive period (month, quarter, half-year or year)

period_startstring date nullable

The start date of the incentive period (month, quarter, half-year or year)

typestring

A valid type according to the payment frequency

Example request

{
  "amount": 50000,
  "amount_tax_type": "net",
  "effective_date": "2021-12-20",
  "note": "Bonus for moving start date to an earlier date",
  "period_end": "2025-01-31",
  "period_start": "2025-01-01",
  "type": "signing_bonus"
}

Response

Success

Example response

{
  "data": {
    "incentive": {
      "amount": 50000,
      "amount_tax_type": "net",
      "effective_date": "2021-12-20",
      "employment_id": "5e55386e-4f4f-4def-92f4-bdc19a5ce77d",
      "expected_payout_date": "2021-12-31",
      "id": "0073fcb5-b669-4e4a-b963-2a47744e75a1",
      "note": "Signing bonus",
      "recurring_incentive_id": "1c130827-f95c-4495-b7cb-5876dce686b8",
      "status": "pending",
      "type": "signing_bonus"
    }
  }
}