Sign in

v1

latestOpenAPI 3.1.02026-07-242735131.1 MB
Recurring Incentives

Create Recurring Incentive

Create a Recurring Incentive, that is, a monthly paid incentive.

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

Scopes

CategoryRead only ScopeWrite only Scope (read access implicit)
Manage expenses (employment_payments)-Manage incentives (incentive:write)
post/v1/incentives/recurring

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 required

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' required

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 required

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
duration_in_monthsstring integer

How many times the payment will repeat. At the moment we only fully support monthly frequency.

This field is only necessary if the recurring incentive has an end date.

employment_idstring required
type'acting_up_allowance' | 'allowance' | 'car_allowance' | 'health_and_wellness_allowance' | 'internet_allowance' | 'meal_allowance' | 'on_call_allowance' | 'parenthood_allowance' | 'phone_allowance' | 'relocation_allowance' | 'travel_allowance' | 'work_from_home_allowance' | 'bonus' | 'holiday_bonus' | 'referral_bonus' | 'retention_bonus' | 'commission' | 'other' | 'overtime' | 'stipend' required

Example request

{
  "amount": 50000,
  "amount_tax_type": "net",
  "duration_in_months": "3",
  "effective_date": "2021-12-20",
  "employment_id": "5e55386e-4f4f-4def-92f4-bdc19a5ce77d",
  "note": "Bonus for moving start date to an earlier date",
  "type": "meal_allowance"
}

Response

Success

Example response

{
  "data": {
    "recurring_incentive": {
      "amount": 50000,
      "amount_tax_type": "net",
      "employment_id": "5e55386e-4f4f-4def-92f4-bdc19a5ce77d",
      "end_date": "2022-12-20",
      "id": "0073fcb5-b669-4e4a-b963-2a47744e75a1",
      "note": "Monthly stipend to buy food",
      "start_date": "2021-12-20",
      "status": "active",
      "type": "meal_allowance"
    }
  }
}