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.

Authentication

This endpoint accepts any one of the following token types:

Company-scoped access token (OAuth2AuthorizationCode) — obtained by a company manager through the Authorization Code flow or the Refresh Token flow. See Authentication for partners.
Company-scoped access token (assertion) (OAuth2CompanyManagerAssertion) — obtained through the urn:ietf:params:oauth:grant-type:jwt-bearer grant for a company manager. See OAuth Assertion.
Customer API token (CustomerAPIToken) — generated by the customer on their Integration Settings page, with the scopes they choose there. See Authorization for customers.

Scopes

Any one of the scopes in a token type's row is enough. all:write works too.

Token type	Category	Read only Scope	Write only Scope (read access implicit)
Company-scoped access token	Manage expenses (employment_payments)	-	Manage incentives (incentive:write)
Company-scoped access token (assertion)	Manage expenses (employment_payments)	-	Manage incentives (incentive:write)
Customer API token	Manage expenses (employment_payments)	-	Manage incentives (incentive:write)

patch/v1/incentives/{id}

Request

Base URL
https://gateway.remote.com
URL
https://gateway.remote.com/v1/incentives/{id}
Auth
- OAuth 2
  Authorization code: /auth/oauth2/authorize
  Token URL: /auth/oauth2/token scopes: https://gateway.remote.com/company.manage
- or OAuth 2
  Authorization code: /auth/oauth2/authorize
  Token URL: /auth/oauth2/token scopes: incentive:write
- or OAuth 2
  Authorization code: /auth/oauth2/authorize
  Token URL: /auth/oauth2/token scopes: all:write
- or OAuth 2
  Client credentials
  Token URL: /auth/oauth2/token scopes: incentive:write
- or OAuth 2
  Client credentials
  Token URL: /auth/oauth2/token scopes: all:write
- or HTTP bearer

Path parameters

idstring required

Incentive ID

Headers

Authorizationstring required

An access token of one of the types listed in this endpoint's Authentication section, as Bearer <ACCESS TOKEN>.

A token from the Refresh Token flow is of the same type as the token issued with that refresh token.

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",
      "payroll_output_category": "incentive",
      "recurring_incentive_id": "1c130827-f95c-4495-b7cb-5876dce686b8",
      "status": "pending",
      "type": "signing_bonus",
      "type_label": "Signing bonus"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.