---
title: "Upsert Earning"
method: PUT
path: "/v2/companies/{companyId}/employees/{employeeId}/earnings"
tags: ["Earnings"]
---

# Upsert Earning

`PUT /v2/companies/{companyId}/employees/{employeeId}/earnings`

## Request

- Base URL: `https://dc1demogw.paylocity.com/api`
- URL: `https://dc1demogw.paylocity.com/api/v2/companies/{companyId}/employees/{employeeId}/earnings`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://api.paylocity.com/IdentityServer/connect/token` scopes: `WebLinkAPI`

Upsert Earning API sends new or updated employee earnings information directly to Paylocity Payroll/HR solution.

## Path parameters

- `companyId` string, required
- `employeeId` string, required

## Request body

- Earning: The employee earning model
  - `agency` string: Third-party agency associated with earning. Must match Company setup.<br />Max length: 10
  - `amount` number: Value that matches CalculationCode to add to gross wages. For percentage (%), enter whole number (10 = 10%). <br />Decimal(12,2)
  - `annualMaximum` number: Year to Date dollar amount not to be exceeded for an earning in the calendar year. Used only with company driven maximums. <br />Decimal(12,2)
  - `calculationCode` string: Defines how earnings are calculated. Common values are *% (percentage of gross), flat (flat dollar amount)*. Defaulted to the Company setup calcCode for earning. <br />Max length: 20
  - `costCenter1` string: Cost Center associated with earning. Must match Company setup.<br /> Max length: 10
  - `costCenter2` string: Cost Center associated with earning. Must match Company setup.<br /> Max length: 10
  - `costCenter3` string: Cost Center associated with earning. Must match Company setup.<br /> Max length: 10
  - `earningCode` string, required: Earning code. Must match Company setup. <br />Max length: 10
  - `effectiveDate` string, paylocity-date: Date earning is active. Defaulted to run date or check date based on Company setup. Common formats are MM-DD-CCYY, CCYY-MM-DD.
  - `endDate` string, paylocity-date: Stop date of an earning. Common formats are MM-DD-CCYY, CCYY-MM-DD.
  - `frequency` string: Needed if earning is applied differently from the payroll frequency (one time earning for example).<br /> Max length: 5
  - `goal` number: Dollar amount. The employee earning will stop when the goal amount is reached.<br /> Decimal(12,2)
  - `hoursOrUnits` number: The value is used in conjunction with the Rate field. When entering Group Term Life Insurance (GTL), it should contain the full amount of the group term life insurance policy. <br /> Decimal(12,2)
  - `isSelfInsured` boolean: Used for ACA. If not entered, defaulted to Company earning setup.
  - `jobCode` string: Job code associated with earnings. Must match Company setup.<br /> Max length: 20
  - `miscellaneousInfo` string: Information to print on the check stub if agency is set up for this earning. <br />Max length: 50
  - `paidTowardsGoal` number: Amount already paid to employee toward goal. <br /> Decimal(12,2)
  - `payPeriodMaximum` number: Maximum amount of the earning on a single paycheck. <br /> Decimal(12,2)
  - `payPeriodMinimum` number: Minimum amount of the earning on a single paycheck. <br /> Decimal(12,2)
  - `rate` number: Rate is used in conjunction with the hoursOrUnits field. <br /> Decimal(12,2)
  - `rateCode` string: Rate Code applies to additional pay rates entered for an employee. Must match Company setup. <br /> Max length: 10
  - `startDate` string, paylocity-date, required: Start date of an earning based on payroll calendar. Common formats are MM-DD-CCYY, CCYY-MM-DD.

## Response `200`

Successfully added or updated

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/paylocity/apis/weblink-api.md) - [All operations](https://skmtc.dev/paylocity/apis/weblink-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paylocity/apis/weblink-api/revisions/8152ed40b412?raw)