add_earnings
Add one-time or recurring earnings like bonuses, commissions, or overtime to employee payroll records in Paylocity. Specify earning codes, amounts, dates, and cost centers for accurate compensation management.
Instructions
Add a one-time or recurring earning to an employee (bonus, commission, stipend, overtime, etc.). Use get_company_codes or check existing earnings for valid earning codes.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| companyId | No | Paylocity company ID (defaults to PAYLOCITY_COMPANY_ID env var) | |
| employeeId | Yes | Paylocity employee ID | |
| earningCode | Yes | Earning code (e.g. BONUS, COMM, OT — company-specific) | |
| amount | No | Dollar amount | |
| rate | No | Rate per hour/unit | |
| hoursOrUnits | No | Number of hours or units | |
| startDate | Yes | Start date YYYY-MM-DD | |
| endDate | No | End date YYYY-MM-DD (omit for one-time) | |
| costCenter1 | No | ||
| costCenter2 | No | ||
| costCenter3 | No |
Implementation Reference
- src/server.ts:556-591 (handler)The handler logic for 'add_earnings' tool, which constructs the payload and makes a PUT request to the Paylocity API.
async ({ companyId, employeeId, earningCode, amount, rate, hoursOrUnits, startDate, endDate, costCenter1, costCenter2, costCenter3, }) => { try { const cid = resolveCompanyId(companyId); const payload: Record<string, any> = { earningCode, startDate, }; if (amount !== undefined) payload.amount = amount; if (rate !== undefined) payload.rate = rate; if (hoursOrUnits !== undefined) payload.hoursOrUnits = hoursOrUnits; if (endDate) payload.endDate = endDate; if (costCenter1) payload.costCenter1 = costCenter1; if (costCenter2) payload.costCenter2 = costCenter2; if (costCenter3) payload.costCenter3 = costCenter3; const result = await client.put( `/v2/companies/${cid}/employees/${employeeId}/earnings`, payload ); return ok({ success: true, result }); } catch (e) { return err(e); - src/server.ts:537-555 (registration)The registration and Zod schema definition for the 'add_earnings' tool.
server.tool( "add_earnings", `Add a one-time or recurring earning to an employee (bonus, commission, stipend, overtime, etc.). Use get_company_codes or check existing earnings for valid earning codes.`, { companyId: companyIdParam, employeeId: z.string().describe("Paylocity employee ID"), earningCode: z .string() .describe("Earning code (e.g. BONUS, COMM, OT — company-specific)"), amount: z.number().optional().describe("Dollar amount"), rate: z.number().optional().describe("Rate per hour/unit"), hoursOrUnits: z.number().optional().describe("Number of hours or units"), startDate: z.string().describe("Start date YYYY-MM-DD"), endDate: z.string().optional().describe("End date YYYY-MM-DD (omit for one-time)"), costCenter1: z.string().optional(), costCenter2: z.string().optional(), costCenter3: z.string().optional(), },