Working with Incentives

📒 Table of contents

Overview

In this guide, you will learn:

  • How to differentiate incentives
  • About the incentive lifecycle
  • How to work with one-time and recurring incentives

Before you get started

Before you get started, ensure that you have an active employment in your company.

Incentives

An Incentive represents all the items outside of regular salary that an employer might need to pay to the employee, for example, commissions, bonuses or allowances. The amount specified is in the currency the person gets paid in.

There are two payment frequencies:

  • One time - when the incentive is created and paid only once, a single event;
  • Monthly - when the incentive is periodicity, it is called a Recurring Incentive. It can repeat for a fixed number of months or it can be indefinite.

Besides that, each incentive has a type. Check the documentation of the Create Incentive / Create Recurring Incentive API Reference to get the updated list of available types. On a side note, not all one-time types are accepted for recurring incentives.

When creating an incentive, it is necessary to provide the effective_date, which determines which payroll cycle the incentive will be paid out in. The incentive is not paid out on the effective date, but during the next payroll cycle.

📅
Since the months don't have the same amount of days, for recurring incentives, if the day of the 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.

Incentives also have the free-form text note field, to add more information about the incentive. It is highly recommended to use that field since the Remote API has some mechanisms in place to prevent the registration of duplicated incentives, and having specific notes helps to differentiate them. For example, in case an employee is to receive two referral bonuses on the same day, this can be mentioned in the notes, such as Referral bonus regarding <people's name or id>.

Incentive lifecycle

The status of an incentive depends on whether it is already associated to a payroll cycle or not. When the incentive is created and it is not yet associated to a payroll cycle, its status is pending. When the incentive is associated to a payroll cycle, its status can be preparing, processing, or paid. When an incentive is cancelled, it is marked as deleted.

⚠️
It is not possible to cancel an one-time incentive if its status is :paid or :processing. Recurring incentives work slightly differently and Remote will only delete scheduled upcoming incentives with the pending status.

Working with one-time incentives

We provide endpoints for all basic operations (create, read, update, delete, and list) for one-time incentives in the /v1/incentives route. For example, to create and update an incentive:

shell
1# create a one-time incentive
2$ curl --location --request POST \
3  --header "Authorization: Bearer <your token>" \
4  --header "Content-Type: application/json" \
5  https://gateway.remote-sandbox.com/v1/incentives \
6  --data '{
7	"amount": 50000,
8  "amount_tax_type": "gross",
9  "effective_date": "2025-12-20",
10  "employment_id": "5509b6b0-5a0a-11ed-a6f6-c38dbde70e6f",
11  "note": "Bonus for moving start date to an earlier date",
12  "type": "signing_bonus"
13}'
14

15{
16   "data":{
17      "incentive":{
18         "amount": 50000,
19         "amount_tax_type": "gross",
20         "effective_date": "2025-12-20",
21         "employment_id": "5509b6b0-5a0a-11ed-a6f6-c38dbde70e6f",
22         "expected_payout_date": null,
23         "id": "e6c42029-d12a-4480-a732-73017991ba8e",
24         "note": "Bonus for moving start date to an earlier date",
25         "recurring_incentive_id": null,
26         "status": "pending",
27         "type": "signing_bonus"
28      }
29   }
30}
31

32# modify the incentive
33$ curl --location --request PATCH \
34  --header "Authorization: Bearer <your token>" \
35  --header "Content-Type: application/json" \
36  https://gateway.remote-sandbox.com/v1/incentives/e6c42029-d12a-4480-a732-73017991ba8e\
37  --data '{
38	"amount": 150000
39}'
40

41{
42   "data":{
43      "incentive":{
44         "amount": 150000,
45         "amount_tax_type": "gross",
46         "effective_date": "2025-12-20",
47         "employment_id": "5509b6b0-5a0a-11ed-a6f6-c38dbde70e6f",
48         "expected_payout_date": null,
49         "id": "e6c42029-d12a-4480-a732-73017991ba8e",
50         "note": "Monthly stipend to buy food",
51         "recurring_incentive_id": "1e74fdc2-7420-4eef-ab0a-b794cbbef4e1",
52         "status": "pending",
53         "type": "meal_allowance"
54      }
55   }
56}

Working with Recurring incentives

Recurring Incentives are an abstraction for scheduled one-time incentives, so we only provide endpoints for the create, list, and delete operations. When creating a recurring incentive, the response returned is the upcoming one-time incentive, but with the recurring_incentive_id field filled.

To modify some information, you must indicate the upcoming one-time incentive. It's not possible to modify in batch all the recurring incentives since some occurrences might have been already paid or processed.

Deleting a recurring incentive cancels the upcoming one-time incentives with the pending status. This request also returns a list of already_processing_incentives , that are occurrences of incentives that cannot be deleted since they're in processing status.

shell
1# create an indefinite recurring incentive
2$ curl --location --request POST \
3  --header "Authorization: Bearer <your token>" \
4  --header "Content-Type: application/json" \
5  https://gateway.remote-sandbox.com/v1/incentives/recurring \
6  --data '{
7	"amount": 50000,
8  "amount_tax_type": "gross",
9  "effective_date": "2025-12-20",
10  "employment_id": "5509b6b0-5a0a-11ed-a6f6-c38dbde70e6f",
11  "note": "Monthly stipend to buy food",
12  "type": "meal_allowance"
13}'
14

15{
16   "data":{
17      "incentive":{
18         "amount": 50000,
19         "amount_tax_type": "gross",
20         "effective_date": "2025-12-20",
21         "employment_id": "5509b6b0-5a0a-11ed-a6f6-c38dbde70e6f",
22         "expected_payout_date": null,
23         "id": "e6c42029-d12a-4480-a732-73017991ba8e",
24         "note": "Monthly stipend to buy food",
25         "recurring_incentive_id": "1e74fdc2-7420-4eef-ab0a-b794cbbef4e1",
26         "status": "pending",
27         "type": "meal_allowance"
28      }
29   }
30}
31

32

33# modify the amount of the incentive
34$ curl --location --request PATCH \
35  --header "Authorization: Bearer <your token>" \
36  --header "Content-Type: application/json" \
37  https://gateway.remote-sandbox.com/v1/incentives/e6c42029-d12a-4480-a732-73017991ba8e \
38  --data '{
39	"amount": 150000
40}'
41

42{
43   "data":{
44      "incentive":{
45         "amount": 150000,
46         "amount_tax_type": "gross",
47         "effective_date": "2025-12-20",
48         "employment_id": "5509b6b0-5a0a-11ed-a6f6-c38dbde70e6f",
49         "expected_payout_date": null,
50         "id": "e6c42029-d12a-4480-a732-73017991ba8e",
51         "note": "Monthly stipend to buy food",
52         "recurring_incentive_id": "1e74fdc2-7420-4eef-ab0a-b794cbbef4e1",
53         "status": "pending",
54         "type": "meal_allowance"
55      }
56   }
57}
58

59

60# delete the recurring incentive
61$ curl --location --request DELETE \
62  --header "Authorization: Bearer <your token>" \
63  --header "Content-Type: application/json" \
64  https://gateway.remote-sandbox.com/v1/incentives/recurring/1e74fdc2-7420-4eef-ab0a-b794cbbef4e1
65

66{
67    "data": {
68        "already_processing_incentives": [],
69        "status": "ok"
70    }
71}