> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filexpress.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Payrolls

> Query processed payrolls, their per-employee detail and assign cost centers to them

**Required permission:** `hr.payrolls` (query) · `hr.payrolls.write` ([assign cost center](#assign-cost-center))

Only **processed** or **paid** payrolls are exposed. Drafts (which can still change) and canceled payrolls are not returned.

## List payrolls

```http theme={null}
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](https://docs.filexpress.app/en/docs/rrhh/nominas.md#payrolls-by-branch)). |

```json theme={null}
{
  "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

```http theme={null}
GET /hr/payrolls/{id}
```

```json theme={null}
{
  "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](https://docs.filexpress.app/en/docs/api/v2/planillas.md#assign-branch). |
| `cost_center_id` | On the payroll: default [cost center](https://docs.filexpress.app/en/docs/api/contabilidad/centros-de-costo.md). 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

```http theme={null}
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).

```json theme={null}
{
  "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](https://docs.filexpress.app/en/docs/api/contabilidad/centros-de-costo.md#distributions) 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](https://docs.filexpress.app/en/docs/api/contabilidad/centros-de-costo.md).
* 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](https://docs.filexpress.app/en/docs/contabilidad/centros-de-costo.md#reassign-cost-centers-in-a-journal-entry) 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`**

```json theme={null}
{
  "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.` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.