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

# Overview

> Instant gross-to-net and net-to-gross salary estimates across 150+ countries

export const ApiExample = ({method = "GET", path, params, body, reference, tenantKey}) => {
  const baseUrl = "https://api.cadanapay.com";
  const query = params ? "?" + Object.entries(params).map(([k, v]) => `${k}=${v}`).join("&") : "";
  const url = `${baseUrl}${path}${query}`;
  const isPlatformPath = (/^\/(v1\/)?platform(\/|$)/).test(path || "");
  const includeTenantKey = tenantKey === undefined ? !isPlatformPath : tenantKey;
  let curl = `curl -X ${method} '${url}' \\\n  -H 'Authorization: Bearer YOUR_API_KEY'`;
  if (includeTenantKey) {
    curl += ` \\\n  -H 'X-MultiTenantKey: YOUR_BUSINESS_TENANT_KEY'`;
  }
  if (body) {
    const formatted = JSON.stringify(body, null, 2);
    curl += ` \\\n  -H 'Content-Type: application/json' \\\n  -d '${formatted}'`;
  }
  return <div>
      <CodeBlock language="bash" filename="bash" wrap>
        {curl}
      </CodeBlock>
      {reference && <div style={{
    marginTop: "-0.5rem",
    marginBottom: "1rem"
  }}>
          <a href={reference} style={{
    fontSize: "0.875rem"
  }}>
            Try it in the playground →
          </a>
        </div>}
    </div>;
};

The Employment Cost Calculator gives you instant salary estimates without creating a person record — one API call with a country code and salary amount. Use it for compensation planning, cost modeling, and hiring decisions.

***

## Gross to Net

Estimate take-home pay from a gross salary:

<ApiExample method="POST" path="/v1/tax/estimate" body={{ countryCode: "MX", type: "gross-to-net", salary: { amount: 4000000, currency: "MXN" } }} reference="/api-reference/tax/tax-calculator/estimate-gross-or-net-salary" />

**Response:**

```json theme={null}
{
  "grossAmount": { "amount": 4000000, "currency": "MXN" },
  "netAmount": { "amount": 3050000, "currency": "MXN" },
  "deductions": [
    { "name": "ISR (Impuesto Sobre la Renta)", "isStatutory": true, "amount": { "amount": 680000, "currency": "MXN" } },
    { "name": "IMSS Employee Contribution", "isStatutory": true, "amount": { "amount": 270000, "currency": "MXN" } }
  ],
  "employerContributions": [
    { "name": "IMSS Employer Contribution", "isStatutory": true, "amount": { "amount": 840000, "currency": "MXN" } },
    { "name": "INFONAVIT (5%)", "isStatutory": true, "amount": { "amount": 200000, "currency": "MXN" } }
  ]
}
```

***

## Net to Gross

Calculate the gross salary needed to achieve a target take-home amount:

<ApiExample method="POST" path="/v1/tax/estimate" body={{ countryCode: "MX", type: "net-to-gross", net: { amount: 3050000, currency: "MXN" } }} reference="/api-reference/tax/tax-calculator/estimate-gross-or-net-salary" />

***

## Response Fields

| Field                      | Description                                                                                                                                 |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| `grossAmount`              | Total salary before deductions                                                                                                              |
| `netAmount`                | Take-home pay after all deductions                                                                                                          |
| `allowances`               | Imputed-income line items (e.g. benefits-in-kind) surfaced by the country engine. Omitted when none apply.                                  |
| `deductions`               | Employee deductions — income tax, social security, etc. Each entry's `isStatutory` flag indicates whether the deduction is mandated by law. |
| `employerContributions`    | Employer-side costs not deducted from the employee's pay                                                                                    |
| `outputCurrency`, `fxRate` | Present only when the request passed `outputCurrency` — echoes the requested currency and the rate applied.                                 |

<Tip>
  Amounts are in the smallest currency unit (e.g., centavos for MXN). An amount of `4000000` in MXN means \$40,000.00 MXN.
</Tip>

***

## When to Use Estimate vs. Calculate

|                             | Estimate                                               | Calculate                                             |
| :-------------------------- | :----------------------------------------------------- | :---------------------------------------------------- |
| **Endpoint**                | `POST /v1/tax/estimate`                                | `POST /v1/tax/calculate`                              |
| **Person record**           | Not needed                                             | Required                                              |
| **Best for**                | Compensation planning, cost modeling, hiring decisions | Payroll processing, year-to-date tracking, compliance |
| **Year-to-date**            | No                                                     | Yes                                                   |
| **Country-specific fields** | No                                                     | Yes (marital status, dependents, etc.)                |

<Note>
  For payroll-grade calculations with year-to-date tracking and country-specific tax profiles, use the [Tax Engine](/tax/getting-started) with a person record.
</Note>

***

## Embeddable Widget

Need a visual calculator for your website? The [Gross-to-Net Salary Calculator widget](/tools/calculator/overview) wraps this same API in an embeddable, themeable UI component that works in any website or CMS.

<CardGroup cols={2}>
  <Card title="Widget Getting Started" icon="rocket" href="/tools/calculator/getting-started">
    Add the calculator to your site with a single script tag
  </Card>

  <Card title="Widget Configuration" icon="gear" href="/tools/calculator/configuration">
    Customize countries, periods, labels, and theming
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Tax Engine Integration" icon="microchip" href="/tax/getting-started">
    Full tax calculations with person records and year-to-date tracking
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/tax/tax-calculator/estimate-gross-or-net-salary">
    Full endpoint documentation
  </Card>
</CardGroup>