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

# Calculate Payroll with Derived Earnings

> Calculates gross-to-net payroll by first generating earnings from time entries and compensation, then calculating all Mexican taxes. This endpoint accepts time entries (start/end times per day) and compensation (daily/weekly/monthly/annual) and automatically derives earnings like SALARY, DOUBLE_OVERTIME, and TRIPLE_OVERTIME.

Available earnings can be obtained from the [List Earnings](/api-reference/endpoint/mexico-payroll/get-earnings) endpoint. The response includes taxes and social security contributions — see [List Taxes](/api-reference/endpoint/mexico-payroll/get-taxes) and [List Social Security Contributions](/api-reference/endpoint/mexico-payroll/get-contributions) for details.



## OpenAPI

````yaml POST /api/mexico-payroll/calculate-with-derived-earnings
openapi: 3.0.3
info:
  title: FluxPayroll API
  description: >-
    API for calculating gross-to-net payroll calculations across different
    countries. Currently supports Mexico with ISR, IMSS, INFONAVIT, and
    state-level payroll tax calculations.
  version: 2.0.0
  contact:
    name: FluxPayroll
    url: https://fluxpayroll.ai
servers:
  - url: https://api.staging.fluxpayroll.ai
    description: Staging
security:
  - apiKey: []
paths:
  /api/mexico-payroll/calculate-with-derived-earnings:
    post:
      tags:
        - Mexico Payroll
      summary: Calculate payroll (G2N) with auto-generated earnings
      description: >-
        Calculates gross-to-net payroll by first generating earnings from time
        entries and compensation, then calculating all Mexican taxes. This
        endpoint accepts time entries (start/end times per day) and compensation
        (daily/weekly/monthly/annual) and automatically derives earnings like
        SALARY, DOUBLE_OVERTIME, and TRIPLE_OVERTIME.


        Available earnings can be obtained from the [List
        Earnings](/api-reference/endpoint/mexico-payroll/get-earnings) endpoint.
        The response includes taxes and social security contributions — see
        [List Taxes](/api-reference/endpoint/mexico-payroll/get-taxes) and [List
        Social Security
        Contributions](/api-reference/endpoint/mexico-payroll/get-contributions)
        for details.
      operationId: calculateMexicoPayrollWithDerivedEarnings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculateWithDerivedEarningsRequest'
      responses:
        '200':
          description: Successful payroll calculation with derived earnings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatePayrollResponse'
              example:
                results:
                  - employeeId: emp-001
                    grossPay: '50000.00'
                    employeeTaxes:
                      MX_IMSS_DISEASE_MATERNITY_PENSIONERS_EE:
                        wageBase: '51241.80'
                        taxAmount: '192.16'
                        taxType: CONTRIBUTIONS
                      MX_IMSS_DISEASE_MATERNITY_KIND_EE:
                        wageBase: '51241.80'
                        taxAmount: '164.92'
                        taxType: CONTRIBUTIONS
                      MX_IMSS_DISEASE_MATERNITY_MONEY_EE:
                        wageBase: '51241.80'
                        taxAmount: '128.10'
                        taxType: CONTRIBUTIONS
                      MX_SAT_ISR:
                        wageBase: '50000.00'
                        taxAmount: '9107.82'
                        taxType: TAX
                        wageBaseContributions:
                          SALARY:
                            earningKey: SALARY
                            grossAmount: '50000.00'
                            exemptionAmount: '0.00'
                            taxableAmount: '50000.00'
                          SOCIAL_WELFARE_BENEFITS:
                            earningKey: SOCIAL_WELFARE_BENEFITS
                            grossAmount: '0.00'
                            exemptionAmount: '0.00'
                            taxableAmount: '0.00'
                      MX_IMSS_DISABILITY_LIFE_EE:
                        wageBase: '51241.80'
                        taxAmount: '320.26'
                        taxType: CONTRIBUTIONS
                      MX_IMSS_RETIREMENT_ADVANCED_AGE_EE:
                        wageBase: '51241.80'
                        taxAmount: '576.47'
                        taxType: CONTRIBUTIONS
                    employerTaxes:
                      MX_IMSS_DISEASE_MATERNITY_KIND_ER:
                        wageBase: '51241.80'
                        taxAmount: '1134.40'
                        taxType: CONTRIBUTIONS
                      MX_IMSS_WORK_RISK:
                        wageBase: '51241.80'
                        taxAmount: '278.52'
                        taxType: CONTRIBUTIONS
                      MX_IMSS_RETIREMENT_OLD_AGE_ER:
                        wageBase: '51241.80'
                        taxAmount: '1024.84'
                        taxType: CONTRIBUTIONS
                      MX_IMSS_RETIREMENT_ADVANCED_AGE_ER:
                        wageBase: '51241.80'
                        taxAmount: '3290.75'
                        taxType: CONTRIBUTIONS
                      MX_IMSS_DISEASE_MATERNITY_PENSIONERS_ER:
                        wageBase: '51241.80'
                        taxAmount: '538.04'
                        taxType: CONTRIBUTIONS
                      MX_IMSS_DISEASE_MATERNITY_MONEY_ER:
                        wageBase: '51241.80'
                        taxAmount: '358.69'
                        taxType: CONTRIBUTIONS
                      MX_IMSS_DISABILITY_LIFE_ER:
                        wageBase: '51241.80'
                        taxAmount: '896.73'
                        taxType: CONTRIBUTIONS
                      MX_INFONAVIT_HOUSING:
                        wageBase: '51241.80'
                        taxAmount: '2562.09'
                        taxType: CONTRIBUTIONS
                      MX_IMSS_NURSERY_SOCIAL_BENEFITS:
                        wageBase: '51241.80'
                        taxAmount: '512.42'
                        taxType: CONTRIBUTIONS
                      MX_AGU_PAYROLL:
                        wageBase: '50000.00'
                        taxAmount: '1250.00'
                        taxType: TAX
                        wageBaseContributions:
                          SALARY:
                            earningKey: SALARY
                            grossAmount: '50000.00'
                            exemptionAmount: '0.00'
                            taxableAmount: '50000.00'
                          TERMINATION_COMPENSATION:
                            earningKey: TERMINATION_COMPENSATION
                            grossAmount: '0.00'
                            exemptionAmount: '0.00'
                            taxableAmount: '0.00'
                    totalEmployerTaxes: '11846.48'
                    totalEmployeeTaxes: '10489.73'
                    netPay: '39510.27'
                    dailySbc: '1737.01'
                    totalEmployeeTax: '9107.82'
                    totalEmployeeContributions: '1381.91'
                    totalEmployerTax: '1250.00'
                    totalEmployerContributions: '10596.48'
        '400':
          description: >-
            Invalid input data (e.g., time entries outside payroll period,
            invalid time format)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error during calculation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CalculateWithDerivedEarningsRequest:
      type: object
      required:
        - employees
        - payrollConfig
      additionalProperties: false
      properties:
        employees:
          type: array
          items:
            $ref: '#/components/schemas/EmployeeGeneratorInput'
          minItems: 1
          description: Array of employees with time entries and compensation
        payrollConfig:
          $ref: '#/components/schemas/PayrollConfig'
          example:
            startDate: '2026-01-01'
            endDate: '2026-01-31'
            period: MONTHLY
        fillDefaultSchedule:
          type: boolean
          default: true
          description: >-
            When true, auto-fills default time entries (standard work hours) for
            work days missing from employee timeEntries
    CalculatePayrollResponse:
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/PayrollResult'
          description: Array of payroll results, one per employee
    ErrorResponse:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error code
          example: VALIDATION_ERROR
        message:
          type: string
          description: Human-readable error message
          example: Invalid input data provided
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                description: Field that caused the error
              message:
                type: string
                description: Specific error message for the field
    EmployeeGeneratorInput:
      type: object
      required:
        - employeeId
        - employeeStartDate
        - compensation
        - timeEntries
        - previousBimesterEarnigs
        - workAddress
        - earnings
      additionalProperties: false
      properties:
        employeeId:
          type: string
          description: Unique employee identifier
          example: emp-001
        employeeStartDate:
          type: string
          format: date
          description: Employee hire date in ISO 8601 format
          example: '2020-01-01'
        compensation:
          $ref: '#/components/schemas/CompensationInput'
          example:
            type: MONTHLY
            amount: 50000
        timeEntries:
          type: array
          items:
            $ref: '#/components/schemas/TimeEntry'
          default: []
          description: Work shifts for the payroll period
        previousBimesterEarnigs:
          type: array
          items:
            $ref: '#/components/schemas/EarningInput'
          default: []
          description: Previous 2 months of earnings for SBC calculation
        workerRiskClass:
          type: string
          enum:
            - I
            - II
            - III
            - IV
            - V
          default: I
          description: IMSS worker risk class
        workAddress:
          $ref: '#/components/schemas/WorkAddress'
        earnings:
          type: array
          items:
            $ref: '#/components/schemas/EarningInput'
          default: []
          description: >-
            Non-derived earnings (e.g., bonuses) to include alongside generated
            earnings
    PayrollConfig:
      type: object
      required:
        - startDate
        - endDate
        - period
      additionalProperties: false
      properties:
        startDate:
          type: string
          format: date
          description: Payroll period start date in ISO 8601 format
          example: '2025-09-01'
        endDate:
          type: string
          format: date
          description: Payroll period end date in ISO 8601 format
          example: '2025-09-30'
        period:
          type: string
          enum:
            - DAILY
            - WEEKLY
            - MONTHLY
            - QUARTERLY
            - SEMI_ANNUAL
            - ANNUAL
          description: Payroll frequency
          example: MONTHLY
    PayrollResult:
      type: object
      required:
        - employeeId
        - grossPay
        - employeeTaxes
        - employerTaxes
        - netPay
        - totalEmployerTax
        - totalEmployerContributions
        - totalEmployeeTax
        - totalEmployeeContributions
        - dailySbc
      properties:
        employeeId:
          type: string
          description: Employee identifier
          example: emp-basic-salary-001
        grossPay:
          type: string
          description: Total gross earnings for the period
          example: '15000.00'
        employeeTaxes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/TaxResult'
          description: Breakdown of employee taxes (ISR, IMSS components, etc.)
        employerTaxes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/TaxResult'
          description: Breakdown of employer taxes and contributions
        netPay:
          type: string
          description: Net pay after all employee taxes and deductions
          example: '13250.45'
        totalEmployerTax:
          type: string
          description: Total employer taxes (taxType = TAX)
          example: '450.00'
        totalEmployerContributions:
          type: string
          description: Total employer contributions (taxType = CONTRIBUTIONS)
          example: '2100.50'
        totalEmployeeTax:
          type: string
          description: Total employee taxes
          example: '1749.55'
        totalEmployeeContributions:
          type: string
          description: Total employee contributions
          example: '350.00'
        dailySbc:
          type: string
          description: >-
            Daily SBC (Salary Base for Contributions) utilized for IMSS
            calculations
          example: '520.55'
    CompensationInput:
      type: object
      required:
        - type
        - amount
      additionalProperties: false
      properties:
        type:
          type: string
          enum:
            - daily
            - weekly
            - monthly
            - annual
          description: Compensation frequency type
          example: monthly
        amount:
          type: number
          minimum: 0
          description: Salary amount in MXN
          example: 15000
    TimeEntry:
      type: object
      required:
        - date
        - startTime
        - endTime
      additionalProperties: false
      properties:
        date:
          type: string
          format: date
          description: Work date in ISO 8601 format
          example: '2025-09-01'
        startTime:
          type: string
          pattern: ^([01]\d|2[0-3]):[0-5]\d$
          description: Shift start time in HH:mm 24-hour format
          example: '09:00'
        endTime:
          type: string
          pattern: ^([01]\d|2[0-3]):[0-5]\d$
          description: Shift end time in HH:mm 24-hour format
          example: '17:00'
        dayOffType:
          type: string
          enum:
            - sick
            - vacation
            - absent
            - work_illness
          description: Type of day off, if applicable
      example:
        date: '2025-09-01'
        startTime: '09:00'
        endTime: '17:00'
    EarningInput:
      type: object
      required:
        - earningCode
        - amount
      additionalProperties: false
      properties:
        earningCode:
          type: string
          description: >-
            Earning type code (e.g., SALARY, DOUBLE_OVERTIME, XMAS,
            VACATION_PREMIUM)
          example: SUNDAY_PREMIUM
        amount:
          type: number
          minimum: 0
          description: Earning amount in MXN
          example: 15000
    WorkAddress:
      type: object
      required:
        - state
      additionalProperties: false
      properties:
        state:
          type: string
          enum:
            - AGU
            - BCN
            - BCS
            - CAM
            - CHH
            - CHP
            - COA
            - COL
            - DIF
            - DUR
            - GRO
            - GUA
            - HID
            - JAL
            - MEX
            - MIC
            - MOR
            - NAY
            - NLE
            - OAX
            - PUE
            - QUE
            - ROO
            - SIN
            - SLP
            - SON
            - TAB
            - TAM
            - TLA
            - VER
            - YUC
            - ZAC
          description: Mexican state code
          example: AGU
    TaxResult:
      type: object
      required:
        - wageBase
        - taxAmount
      properties:
        wageBase:
          type: string
          description: Taxable income base for this tax
          example: '15000.00'
        taxAmount:
          type: string
          description: Calculated tax amount
          example: '1200.50'
        subsidy:
          type: string
          description: Tax subsidy amount, if applicable (e.g., employment subsidy for ISR)
          example: '0.00'
  securitySchemes:
    apiKey:
      type: apiKey
      name: x-api-key
      in: header

````