Skip to main content
POST
/
v1
/
payroll
/
calculate
Calculate payroll for a single employee
curl --request POST \
  --url https://api.example.com/v1/payroll/calculate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "country": "<string>",
  "scheme": "<string>",
  "year": 2025,
  "period": {
    "type": "monthly",
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "days": 16
  },
  "employee": {
    "id": "<string>",
    "daily_salary": 800,
    "monthly_salary": 1,
    "factor_integracion": 1.0493,
    "risk_class_rate": 0.00543,
    "overtime_amount": "0",
    "sunday_bonus_days": 0,
    "grocery_voucher_amount": "0",
    "infonavit_credit_amount": "0",
    "overrides": {}
  },
  "employer": {
    "id": "<string>",
    "rfc": "ABC123456XY0"
  },
  "overrides": {},
  "options": {
    "include_audit_trail": true,
    "include_diagram": false,
    "precision": 2
  }
}
'
{
  "id": "<string>",
  "country": "<string>",
  "scheme": "<string>",
  "year": 123,
  "period": {
    "type": "monthly",
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "days": 16
  },
  "employee_id": "<string>",
  "summary": {
    "gross_salary": "<string>",
    "total_perceptions": "<string>",
    "total_deductions": "<string>",
    "net_salary": "<string>",
    "employer_contributions_total": "<string>",
    "employer_total_cost": "<string>"
  },
  "perceptions": [
    {
      "id": "<string>",
      "label": "<string>",
      "amount": "<string>",
      "taxable": true,
      "imss_base": true,
      "tags": [
        "<string>"
      ]
    }
  ],
  "deductions": [
    {
      "id": "<string>",
      "label": "<string>",
      "amount": "<string>",
      "tags": [
        "<string>"
      ],
      "bracket_applied": {}
    }
  ],
  "taxable_bases": [
    {
      "id": "<string>",
      "label": "<string>",
      "amount": "<string>",
      "formula": "<string>"
    }
  ],
  "employer_contributions": [
    {
      "table_id": "<string>",
      "label": "<string>",
      "total": "<string>",
      "components": [
        {
          "id": "<string>",
          "label": "<string>",
          "base": "<string>",
          "rate": "<string>",
          "amount": "<string>"
        }
      ]
    }
  ],
  "dsl_version": "<string>",
  "computed_at": "2023-11-07T05:31:56Z",
  "status": "success",
  "audit_trail": [
    {}
  ]
}

Authorizations

​
Authorization
string
header
required

API key authentication. Send your API key as: Authorization: Bearer <your_api_key>

Body

application/json

Request body for POST /v1/payroll/calculate.

Calculates payroll for a single employee. The most common endpoint — used for payroll runs, payslip generation, and ad-hoc queries.

​
country
string
required

ISO 3166-1 alpha-2 country code (uppercase).

Pattern: ^[A-Z]{2}$
Example:

"MX"

​
scheme
string
required

Payroll scheme identifier (lowercase). Use GET /v1/payroll/schemes/{country} to list available schemes.

Example:

"ordinario"

​
year
integer
required

Calendar year for the payroll calculation.

Required range: 2020 <= x <= 2030
Example:

2024

​
period
Period · object
required

Payroll period definition.

​
employee
EmployeeInput · object
required

Employee-side inputs for a payroll calculation.

​
employer
EmployerInput · object
required

Employer-side inputs for a payroll calculation.

​
overrides
Overrides · object

Request-level overrides. Merged with employee.overrides. Request-level values take precedence.

​
options
CalculationOptions · object

Response options. Do not affect the calculation result.

Response

Calculation successful.

Full single-employee payroll calculation result.

All monetary values are JSON strings. Parse with your language's Decimal library before doing any arithmetic.

​
id
string
required

Globally unique calculation ID (ULID). Stable and sortable by time.

Example:

"01HX9B2KM3V4W5X6Y7Z8A9B0CD"

​
country
string
required
​
scheme
string
required
​
year
integer
required
​
period
Period · object
required

Payroll period definition.

​
employee_id
string
required

Employee ID echoed from the request.

​
summary
PayrollSummary · object
required

High-level financial summary of the payroll calculation.

​
perceptions
PerceptionResponse · object[]
required
​
deductions
DeductionResponse · object[]
required
​
taxable_bases
TaxableBaseResponse · object[]
required
​
employer_contributions
EmployerContributionResponse · object[]
required
​
dsl_version
string
required

Version string of the DSL rule set used for this calculation.

Example:

"2024.2"

​
computed_at
string<date-time>
required

UTC timestamp when this calculation was performed.

​
status
string
default:success
Allowed value: "success"
​
audit_trail
Audit Trail · object[] | null

Step-by-step calculation trace. Each step shows the formula, resolved inputs, and result. Null when include_audit_trail=false.