> ## Documentation Index > Fetch the complete documentation index at: https://docs.cadanapay.com/llms.txt > Use this file to discover all available pages before exploring further. # Save > Save a payroll ## OpenAPI ````yaml /openapi/workforce-management.yaml post /v1/payrolls/{payrollId}/save openapi: 3.0.0 info: description: APIs for interacting with Cadana Payroll Platform version: 1.0.0 title: Business Workforce Management termsOfService: https://cadanapay.com/terms-and-conditions contact: email: api@cadanapay.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.cadanapay.com description: Prod Server - url: https://dev-api.cadanapay.com description: Dev Server security: - Authorization: [] tags: - name: Custom Auth description: APIs for interacting with Custom Authentication - name: Persons description: APIs for interacting with the HR module - name: Milestones description: APIs for milestone-based contractor pay - name: Instant Pay description: APIs for interacting with Instant Pay functionality - name: Users description: APIs for interacting with employee/contractor Cadana accounts - name: Files description: APIs for interacting with file uploads - name: Payrolls description: APIs for interacting with Payroll - name: Platform description: Platform APIs for interacting with businesses - name: Businesses description: APIs for interacting with Business - name: Contracts description: APIs for interacting with contracts - name: Sandbox description: APIs for relevant sandbox simulations - name: Invoices description: APIs for interacting with invoices - name: Reimbursements description: APIs for interacting with reimbursements - name: Entities description: >- APIs for managing legal sub-entities (subsidiaries, branches) under a parent business paths: /v1/payrolls/{payrollId}/save: post: tags: - Payrolls summary: Save description: Save a payroll operationId: savePayroll parameters: - $ref: '#/components/parameters/payrollId' - in: query name: includeFxRates required: false schema: type: boolean default: false description: > When `true`, the response is `200 OK` with the captured FX rates in the body, keyed as `-` currency pairs. Any other value (or omitting the parameter) returns `204 No Content`. - $ref: '#/components/parameters/XMultiTenantKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/SavePayroll' example: payrollDate: '2026-03-01' payPeriod: fromDate: '2026-02-01' toDate: '2026-02-28' entries: - personId: 8ab2ba37-3c37-485d-9af9-122d11c96bf9 salary: amount: 500000 currency: USD - personId: ca49c55b-12c7-4085-8a0d-ebd006ed8002 salary: amount: 375000 currency: USD responses: '200': description: > FX rates captured at save time. Returned only when `includeFxRates=true`. Keys are `-` currency pairs; each value is the number of salary-currency units per unit of funding currency. Salary-currency amounts are divided by the rate to get the funding-currency debit. content: application/json: schema: type: object properties: fxRates: type: object description: > Map of `-` currency pair to the captured rate. additionalProperties: type: number example: fxRates: USD-PHP: 58.75 USD-EUR: 0.9217 '204': description: >- Successful operation. Default response when `includeFxRates` is omitted or not `true`. '400': $ref: '#/components/responses/BadRequestError' security: - Authorization: [] components: parameters: payrollId: name: payrollId in: path description: The unique identifier for the payroll required: true schema: type: string format: uuid XMultiTenantKey: name: X-MultiTenantKey in: header required: false schema: type: string description: >- Required when using a Platform API token. The tenant key identifying which business to operate on. schemas: SavePayroll: required: - payrollDate - payPeriod - entries type: object properties: payrollDate: type: string description: payroll date format: date payPeriod: $ref: '#/components/schemas/payPeriod' fxRateExpiresAt: type: string format: date-time description: > Maximum time the quoted FX rates are valid (RFC 3339). If omitted, spot rates are used. example: '2025-06-15T23:59:59Z' entries: type: array items: $ref: '#/components/schemas/payrollEntryInput' customFees: type: array description: > Optional custom fee line items that supplement the standard per-seat subscription fees. items: type: object required: - name - amount properties: name: type: string description: Name of the fee example: Platform Fee amount: $ref: '#/components/schemas/amount' metadata: type: object description: >- Optional opaque metadata attached to the fee. Stored and returned unchanged. Not used in tax calculations or reports. Do not place regulated PII here. Keys must be 1-50 characters. additionalProperties: type: string maxLength: 200 maxProperties: 20 example: team: engineering region: emea tags: $ref: '#/components/schemas/tags' payPeriod: type: object properties: fromDate: type: string description: start date format: date toDate: type: string description: end date format: date payrollEntryInput: required: - salary - personId type: object properties: personId: $ref: '#/components/schemas/uuid' salary: allOf: - $ref: '#/components/schemas/amount' description: >- Base rate per the person's compensation frequency. For a salaried-monthly person this is the period amount; for an hourly/daily person this is the rate per hour/day. The frequency itself comes from the person's stored `compInfo.frequency` — never sent on the entry. timeWorked: type: number description: >- Units of work in the period (e.g. `160` hours, `20` days, or `1` for a salaried-monthly person). The unit is implied by the person's `compInfo.frequency`. When omitted the engine defaults to `1`, which is the correct value for salaried workers paid one period. example: 160 overtime: allOf: - $ref: '#/components/schemas/amount' description: >- Overtime rate (when paired with `overtimeWorked`, e.g. $37.50/hr × 10 hours) or a flat overtime amount (when `overtimeWorked` is omitted, e.g. $500 of overtime this period). Sending `overtimeWorked` without `overtime` is rejected. overtimeWorked: type: number description: >- Overtime units worked in the period (e.g. `10` hours of overtime). Multiplies against `overtime` when both are provided. Must be non-negative. The unit is implied by the person's `compInfo.frequency`. example: 10 bonus: $ref: '#/components/schemas/amount' commission: $ref: '#/components/schemas/amount' allowances: type: array description: >- Non-statutory allowance line items applied to this entry (e.g. housing, transport stipends). Each item carries a `name`, `isTaxable` flag (defaults to false when omitted — pass true explicitly for taxable allowances), and `amount`. items: $ref: '#/components/schemas/allowance' deductions: type: array description: >- Voluntary (non-statutory) deduction line items to apply this period — e.g. voluntary pension top-ups, garnishments, equipment repayments. Items with `isStatutory: true` are silently dropped (statutory items like income tax and social security are computed by the tax engine and would otherwise double-count). This lets you round-trip a payload fetched via `GET` without having to filter engine-computed items first. items: $ref: '#/components/schemas/deduction' invoiceIds: type: array description: >- IDs of approved contractor invoices to pay through this entry. Only valid on a contractor payroll: each invoice must be a contractor self-submitted invoice in an approved state and belong to this entry's person. The invoice is marked paid when the payroll completes. items: $ref: '#/components/schemas/uuid' metadata: type: object description: >- Optional opaque metadata attached to the entry. Stored and returned unchanged. Not used in tax calculations or reports. Do not place regulated PII here. Keys must be 1-50 characters. additionalProperties: type: string maxLength: 200 maxProperties: 20 example: team: engineering region: emea amount: type: object required: - amount - currency properties: amount: type: integer description: value in lowest denomination example: 10000 currency: type: string description: currency example: USD tags: type: object description: Any custom data you want to store BadRequestError: description: Bad input provided by client allOf: - $ref: '#/components/schemas/Error' - type: object properties: params: description: A map for meta data around the error that occurred type: object example: code: invalid_request_body message: The request body provided is not valid params: field: Value is invalid. uuid: type: string format: uuid example: 8ef9a712-cdae-4110-b1ea-9ba95abbee6e allowance: type: object required: - name - isTaxable - amount properties: name: type: string example: Housing isTaxable: type: boolean description: Whether this allowance is included in taxable income. example: true amount: $ref: '#/components/schemas/amount' deduction: type: object required: - name - isStatutory - amount properties: name: type: string example: Income Tax isStatutory: type: boolean description: >- Whether this deduction is mandated by law (e.g., income tax, social security) versus a non-statutory item. example: true amount: $ref: '#/components/schemas/amount' Error: type: object properties: code: description: A machine parsable error code type: string enum: - invalid_request_body - resource_not_found - forbidden - internal_error message: description: A human readable message describing the error type: string responses: BadRequestError: description: Bad input provided by client content: application/json: schema: $ref: '#/components/schemas/BadRequestError' securitySchemes: Authorization: type: http scheme: bearer bearerFormat: API_SECRET_KEY ````