> ## 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.

# Calculate Taxes

> Calculate taxes for an existing Cadana person. The person's address determines the jurisdiction, and their stored compensation and tax profile provide calculation inputs (overridden by `salary` when supplied).

Beyond the base salary, the request accepts the same per-entry earnings as a payroll entry — `allowances`, `bonus`, `overtime`, and voluntary `deductions` — and computes them identically to a payroll run.




## OpenAPI

````yaml /openapi/global-tax.yaml post /v1/tax/calculate
openapi: 3.0.0
info:
  title: Global Tax Engine
  version: 1.0.0
  description: API module for calculating taxes globally
  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: Tax Calculator
    description: APIs for tax calculations
paths:
  /v1/tax/calculate:
    post:
      tags:
        - Tax Calculator
      summary: Calculate Taxes
      description: >
        Calculate taxes for an existing Cadana person. The person's address
        determines the jurisdiction, and their stored compensation and tax
        profile provide calculation inputs (overridden by `salary` when
        supplied).


        Beyond the base salary, the request accepts the same per-entry earnings
        as a payroll entry — `allowances`, `bonus`, `overtime`, and voluntary
        `deductions` — and computes them identically to a payroll run.
      operationId: calculateTaxesForPerson
      parameters:
        - $ref: '#/components/parameters/XMultiTenantKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculateTaxesRequest'
            examples:
              existingPerson:
                summary: Calculate for existing person
                value:
                  personId: 81933bed-97ba-4477-81a7-b8c5ab507b6f
                  salary:
                    amount: 4000000
                    currency: MXN
                  additionalAttributes:
                    ytdSalary: 4000000
              withEarnings:
                summary: Salary plus allowances and a bonus
                value:
                  personId: 81933bed-97ba-4477-81a7-b8c5ab507b6f
                  salary:
                    amount: 4000000
                    currency: MXN
                  bonus:
                    amount: 500000
                    currency: MXN
                  allowances:
                    - name: Meal Allowance
                      isTaxable: true
                      amount:
                        amount: 200000
                        currency: MXN
      responses:
        '200':
          $ref: '#/components/responses/CalculateTaxesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
      security:
        - Authorization: []
components:
  parameters:
    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:
    CalculateTaxesRequest:
      type: object
      required:
        - personId
      properties:
        personId:
          type: string
          description: >-
            ID of the Cadana person to calculate taxes for. The person's address
            determines the jurisdiction, and their stored compensation and tax
            profile provide calculation inputs.
        salary:
          $ref: '#/components/schemas/Amount'
        bonus:
          allOf:
            - $ref: '#/components/schemas/Amount'
          description: Bonus amount for the period, included in gross and taxable income.
        overtime:
          allOf:
            - $ref: '#/components/schemas/Amount'
          description: Overtime amount for the period.
        allowances:
          type: array
          description: >-
            Allowance line items (e.g. housing, meal stipends). Each carries a
            `name`, `isTaxable`, and `amount`. Pass `isTaxable` explicitly —
            when omitted it defaults to `false`, meaning the allowance counts
            toward gross pay but not taxable income.
          items:
            type: object
            required:
              - name
              - amount
            properties:
              name:
                type: string
                example: Meal Allowance
              isTaxable:
                type: boolean
                default: false
                description: >-
                  Whether this allowance is included in taxable income. Defaults
                  to `false` when omitted.
              amount:
                $ref: '#/components/schemas/Amount'
        deductions:
          type: array
          description: >-
            Voluntary (non-statutory) deduction line items to apply. Items with
            `isStatutory: true` are ignored — statutory items like income tax
            and social security are computed by the engine.
          items:
            type: object
            required:
              - name
              - amount
            properties:
              name:
                type: string
                example: Gym Membership
              isStatutory:
                type: boolean
                default: false
              amount:
                $ref: '#/components/schemas/Amount'
        additionalAttributes:
          type: object
          description: >-
            Country-specific calculation inputs (e.g. `ytdSalary`,
            `riskCategory`). Use `GET /v1/tax/fields?country={code}` to discover
            what each jurisdiction accepts. Numeric fields are expressed in
            major currency units — e.g. India's `hraReceived`, `rentPaid`,
            `declared80c`, and `annualBaseSalary` are whole rupees — unlike
            `amount` objects, which use the lowest denomination.
    Amount:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: number
          description: value in lowest denomination
          example: 10000
        currency:
          type: string
          description: currency
          example: BRL
    CalculateTaxesResponse:
      type: object
      required:
        - personId
        - grossAmount
        - netAmount
        - deductions
        - employerContributions
      properties:
        personId:
          type: string
          description: ID of the person taxes were calculated for
        grossAmount:
          $ref: '#/components/schemas/Amount'
        netAmount:
          $ref: '#/components/schemas/Amount'
        allowances:
          type: array
          description: >-
            Imputed-income line items (e.g. benefits-in-kind) surfaced by the
            country engine. Omitted when none apply.
          items:
            $ref: '#/components/schemas/Allowance'
        deductions:
          type: array
          items:
            $ref: '#/components/schemas/Deduction'
        employerContributions:
          type: array
          items:
            $ref: '#/components/schemas/Deduction'
        summary:
          $ref: '#/components/schemas/CalculateTaxesSummary'
    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.
    Allowance:
      type: object
      required:
        - name
        - isTaxable
        - amount
      properties:
        name:
          type: string
        isTaxable:
          type: boolean
          description: Whether the allowance is part of taxable income.
        amount:
          $ref: '#/components/schemas/Amount'
    Deduction:
      type: object
      required:
        - name
        - isStatutory
        - amount
      properties:
        name:
          type: string
        isStatutory:
          type: boolean
          description: >-
            Whether the deduction is mandated by law (statutory) versus an
            optional voluntary deduction.
        amount:
          $ref: '#/components/schemas/Amount'
    CalculateTaxesSummary:
      type: object
      properties:
        gross:
          $ref: '#/components/schemas/CalculateTaxesLineItem'
        deductions:
          type: array
          items:
            $ref: '#/components/schemas/CalculateTaxesLineItem'
        net:
          $ref: '#/components/schemas/CalculateTaxesLineItem'
        employerContributions:
          type: array
          items:
            $ref: '#/components/schemas/CalculateTaxesLineItem'
    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
    CalculateTaxesLineItem:
      type: object
      required:
        - name
        - amount
        - calculation
      properties:
        name:
          type: string
        amount:
          type: number
        calculation:
          $ref: '#/components/schemas/CalculationDetails'
    CalculationDetails:
      type: object
      properties:
        description:
          type: string
        inputValues:
          type: object
          additionalProperties:
            type: number
        formula:
          type: string
        steps:
          type: array
          items:
            type: string
  responses:
    CalculateTaxesResponse:
      description: Calculate taxes response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CalculateTaxesResponse'
          examples:
            brazilianTaxCalculation:
              $ref: '#/components/examples/TaxCalculationExample'
    BadRequestError:
      description: Bad input provided by client
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestError'
  examples:
    TaxCalculationExample:
      summary: Example Brazilian tax calculation response
      value:
        personId: 81933bed-97ba-4477-81a7-b8c5ab507b6f
        grossAmount:
          amount: 1000000
          currency: BRL
        netAmount:
          amount: 761244
          currency: BRL
        deductions:
          - name: INSS (Instituto Nacional do Seguro Social)
            isStatutory: true
            amount:
              amount: 82839
              currency: BRL
          - name: IRRF (Imposto de Renda Retido na Fonte)
            isStatutory: true
            amount:
              amount: 155917
              currency: BRL
        employerContributions:
          - name: FGTS (Fundo de Garantia do Tempo de Serviço)
            isStatutory: true
            amount:
              amount: 80000
              currency: BRL
        summary:
          gross:
            name: Gross Salary
            amount: 1000000
            calculation:
              description: Monthly base salary calculation
              inputValues:
                baseSalary: 1000000
              formula: baseSalary
              steps:
                - 'Base salary amount: R$10000.00'
          deductions:
            - name: INSS (Instituto Nacional do Seguro Social)
              amount: 82839
              calculation:
                description: >-
                  Brazilian Social Security contribution based on 2024 INSS
                  tables
                inputValues:
                  grossSalary: 10000
                  bracket1Rate: 0.075
                  bracket2Rate: 0.09
                  bracket3Rate: 0.12
                  bracket4Rate: 0.14
                  bracket1Limit: 1320
                  bracket2Limit: 2571.29
                  bracket3Limit: 3856.94
                  bracket4Limit: 7507.49
                formula: Progressive rate calculation based on salary brackets
                steps:
                  - 'Bracket 1: 1320.00 * 7.5% = 99.00'
                  - 'Bracket 2: (2571.29 - 1320.00) * 9% = 112.62'
                  - 'Bracket 3: (3856.94 - 2571.29) * 12% = 154.28'
                  - 'Bracket 4: (7507.49 - 3856.94) * 14% = 462.49'
                  - 'Total INSS contribution: R$828.39'
            - name: IRRF (Imposto de Renda Retido na Fonte)
              amount: 155917
              calculation:
                description: Brazilian Income Tax calculation based on 2024 rates
                inputValues:
                  grossSalary: 10000
                  inssDeduction: 828.39
                  baseCalculation: 9171.61
                  dependentsDeduction: 0
                  irrfRate: 0.275
                  deduction: 869.36
                formula: (baseCalculation * irrfRate) - deduction
                steps:
                  - 'Gross salary: R$10000.00'
                  - 'INSS deduction: R$828.39'
                  - 'Base for IRRF: R$9171.61'
                  - 'Apply 27.5% rate: R$9171.61 * 0.275 = R$2522.19'
                  - 'Deduction amount: R$869.36'
                  - 'Final IRRF: R$1559.17'
          net:
            name: Net Salary
            amount: 761244
            calculation:
              description: Final take-home pay calculation
              inputValues:
                grossSalary: 10000
                inssDeduction: 828.39
                irrfDeduction: 1559.17
              formula: grossSalary - inssDeduction - irrfDeduction
              steps:
                - 'Gross salary: R$10000.00'
                - 'INSS deduction: R$828.39'
                - 'IRRF deduction: R$1559.17'
                - 'Net salary: R$7612.44'
          employerContributions:
            - name: FGTS (Fundo de Garantia do Tempo de Serviço)
              amount: 80000
              calculation:
                description: Employer's FGTS contribution calculation
                inputValues:
                  grossSalary: 10000
                  fgtsRate: 0.08
                formula: grossSalary * fgtsRate
                steps:
                  - 'Calculate 8% FGTS: R$10000.00 * 8% = R$800.00'
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      bearerFormat: API_SECRET_KEY

````