Payrolls

Required permission: hr.payrolls (query) · hr.payrolls.write (assign cost center) Only processed or paid payrolls are exposed. Drafts (which can still change) and canceled payrolls are not returned.

List payrolls

GET /hr/payrolls?start_date=2026-01-01&end_date=2026-12-31

Parameter	Required	Description
`start_date`, `end_date`	Yes	Returns the payrolls whose period overlaps the range (maximum 370 days).
`status`	No	`processed` or `paid`.
`branch_id`	No	Only the payrolls of that branch (businesses with payrolls by branch).

{
  "status": true,
  "data": [
    {
      "id": "uuid",
      "name": "Primera quincena octubre 2026",
      "start_date": "2026-10-01",
      "end_date": "2026-10-15",
      "status": "paid",
      "branch_id": null,
      "cost_center_id": "c3a1...",
      "employees": 12,
      "total_net_amount": 4820.35
    }
  ]
}

Payroll detail

GET /hr/payrolls/{id}

{
  "status": true,
  "data": {
    "id": "uuid",
    "name": "Primera quincena octubre 2026",
    "start_date": "2026-10-01",
    "end_date": "2026-10-15",
    "status": "paid",
    "cost_center_id": "c3a1...",
    "total_net_amount": 4820.35,
    "details": [
      {
        "employee_id": "uuid",
        "employee_name": "María López",
        "document_number": "01234567-8",
        "cost_center_id": null,
        "net_amount": 371.29,
        "payment_status": "paid",
        "payment_date": "2026-10-15",
        "earnings": [
          { "name": "Horas extra", "concept": "overtime", "quantity": 4, "amount": 28.33 }
        ],
        "deductions": [
          { "name": "ISSS Laboral", "concept": "policy", "quantity": null, "amount": 13.60 },
          { "name": "AFP Laboral", "concept": "policy", "quantity": null, "amount": 32.86 },
          { "name": "Inasistencias", "concept": "absence", "quantity": 1, "amount": 28.33 },
          { "name": "Renta (ISR)", "concept": "income_tax", "quantity": null, "amount": 1.95 }
        ],
        "employer_contributions": [
          { "name": "ISSS Patronal", "concept": "policy", "quantity": null, "amount": 34.00 },
          { "name": "AFP Patronal", "concept": "policy", "quantity": null, "amount": 39.66 }
        ]
      }
    ]
  }
}

Field	Description
`branch_id`	The payroll’s branch; `null` if it is business-wide. To assign it, use API v2.
`cost_center_id`	On the payroll: default cost center. In each detail: the employee’s own center (`null` = uses the payroll’s).
`net_amount`	Net amount payable to the employee.
`earnings`	Income in addition to the period’s salary (overtime, bonuses).
`deductions`	Withholdings and deductions (contributions, income tax, absences, unpaid leave).
`employer_contributions`	Employer contributions. They do not affect the employee’s net pay.
`concept`	`policy` (payroll policy), `income_tax` (income tax), `absence` (absences), `unpaid_leave` (unpaid leave) or `overtime` (overtime). It can be `null` in older payrolls.
`quantity`	Days of absence or overtime hours, depending on the concept.

Assign cost center

PUT /hr/payrolls/{id}/cost-center

Required permission: hr.payrolls.write Sets the payroll’s cost center and, if needed, a different center for some employees (for example, to split salary expense across areas).

{
  "cost_center_id": "c3a1...",
  "details": [
    { "employee_id": "uuid-empleado-1", "cost_center_id": "c3b7..." },
    { "employee_id": "uuid-empleado-2", "cost_center_id": null }
  ]
}

Field	Required	Description
`cost_center_id`	No	The payroll’s center. If you send it as `null`, it is removed; if you omit it, it does not change.
`details`	No	Per-employee centers (maximum 2000).
`details[].employee_id`	Yes, with `details`	Employee included in the payroll.
`details[].cost_center_id`	No	The employee’s center; `null` makes it use the payroll’s.
`cost_center_distribution_id`	No	Distribution of the payroll instead of a center. Mutually exclusive with `cost_center_id` at the same level. `null` removes it; if you omit it, it does not change.
`details[].cost_center_distribution_id`	No	The employee’s distribution. Mutually exclusive with `cost_center_id` at the same level.

Behavior

The center must belong to the company, be active and be a leaf center (with no active sub-centers). Look up the IDs with Cost centers.
When the payroll is posted to the books, salary expenses and employer contributions are grouped by account and center (the employee’s or, if they have none, the payroll’s). Withholdings and liabilities are left without a center.
If the payroll has already been posted, the change does not modify the existing journal entry: fix it with the center reassignment in FileXpress.
With a distribution, the employee’s (or the payroll’s) expense is split among its centers by percentage when posting.
If there is an error in any line, no change is applied.

Response 200

{
  "status": true,
  "data": {
    "id": "uuid",
    "cost_center_id": "c3a1...",
    "cost_center_distribution_id": null,
    "details": [
      { "employee_id": "uuid-empleado-1", "cost_center_id": "c3b7...", "cost_center_distribution_id": null },
      { "employee_id": "uuid-empleado-2", "cost_center_id": null, "cost_center_distribution_id": "d7e2..." }
    ]
  }
}

Errors

Code	Cause
`403`	The integration does not have the `hr.payrolls.write` permission.
`404`	`Payroll not found` (nonexistent, deleted or from another company).
`422`	`Validation errors`; for example `details.0.employee_id`: `El empleado no pertenece a esta planilla.` or `cost_center_id`: `El centro de costo … tiene subcentros; seleccione un centro hoja.`

Getting Started

API v2

Billing

Human Resources

Accounting

Inventory

Projects

Receivables & Payables

Pricing & Promotions

Cash

Interactive reference

List payrolls

Payroll detail

Assign cost center

​List payrolls

​Payroll detail

​Assign cost center

List payrolls

Payroll detail

Assign cost center