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

# Calculations

> Use the `calculation` object to get tax rates

The `calculation` object contains tax rate information. A calculation also includes a `calculation_id` that you'll use to record a `transaction` for filing.

## When to create Calculations

Calculations should be used any time you need to calculate sales tax before charging a customer for a transaction. Most e-commerce clients will submit a `POST` to `/tax/calculations` during their checkout flow after the end customer has submitted their address, but before collecting payment.

<img src="https://mintcdn.com/numeralhq/og90jNpWDBl19utB/images/core-flow.png?fit=max&auto=format&n=og90jNpWDBl19utB&q=85&s=e3b1053d5e9056bb9d736444cf850f73" alt="core flow" width="1362" height="1328" data-path="images/core-flow.png" />

## How to create Calculations

<Accordion title="Calculation Request">
  ```
  curl --request POST \
    --url https://api.numeralhq.com/tax/calculations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --header 'X-API-Version: 2024-09-01' \
    --data '{
    "customer": {
      "address": {
        "address_line_1": "3990 N County Rd 300 E",
        "address_city": "Danville",
        "address_province": "IN",
        "address_postal_code": "46122",
        "address_country": "US",
        "address_type": "shipping"
      }
    },
    "order_details": {
      "customer_currency_code": "USD",
      "tax_included_in_amount": false,
      "line_items": [
        {
          "reference_line_item_id": "line_123456789",
          "product_category": "GENERAL_MERCHANDISE",
          "amount": 200,
          "quantity": 2
        }
      ]
    }
  }'
  ```
</Accordion>

<Accordion title="Sample Response">
  ```json theme={null}
  {
    "calculation_id": "calc_17364047950082c1fd8f0-f763-40f8-8c02-e8fc9ded0944",
    "object": "tax.calculation",
    "line_items": [
      {
        "line_item_id": "line_987654321",
        "reference_product_id": "temp-a4a427d4-42fc-47f1-9092-c74f935438a3",
        "reference_product_name": "temp-a4a427d4-42fc-47f1-9092-c74f935438a3",
        "product_tax_code": "GENERAL_MERCHANDISE",
        "tax_included_in_amount": true,
        "tax_jurisdictions": [
          {
            "tax_rate": 0.07,
            "rate_type": "REDUCED_RATE",
            "jurisdiction_name": "State"
          }
        ],
        "tax_amount": 14,
        "amount_excluding_tax": 200,
        "amount_including_tax": 214
      }
    ],
    "total_tax_amount": 14,
    "total_amount_excluding_tax": 200,
    "expires_at": 1714787673,
    "testmode": "false"
  }
  ```
</Accordion>

We return both the aggregate tax information as well as a detailed breakdown for each line item. Many users will just use the `total_tax_amount` to identify what to charge a user, but you will always have the details as you need them.

## Request Parameters

### Customer Object

```json theme={null}
{
  "customer": {
    "id": "cus_123456789", // Optional customer ID
    "address": {
      "address_line_1": "3990 N County Rd 300 E",
      "address_line_2": "Unit 2", // Optional
      "address_city": "Danville",
      "address_province": "IN",
      "address_postal_code": "46122",
      "address_country": "US",
      "address_type": "shipping" // "shipping" or "billing"
    }
  }
}
```

The customer object requires an address for tax calculation purposes.

### Order Details

```json theme={null}
{
  "order_details": {
    "customer_currency_code": "USD", // Supports EUR, RON, PLN, DKK, HUF, CZK, BGN, SEK, USD, CAD
    "tax_included_in_amount": false,
    "line_items": [
      {
        "reference_line_item_id": "line_123456789", // Optional
        "reference_product_id": "p-1233543", // Required if no product_category
        "product_category": "GENERAL_MERCHANDISE", // Required if no reference_product_id
        "fallback_product_category": "GENERAL_MERCHANDISE", // Optional - used if reference_product_id is not found in Numeral
        "amount": 200, // In currency's smallest unit (e.g., cents for USD, whole units for JPY)
        "quantity": 2
      }
    ]
  }
}
```

* **`fallback_product_category`** (string, optional): If you pass a `reference_product_id` that does not exist in Numeral, the calculation falls back to this product category instead of returning a 400. Must be a valid product category from the Numeral taxonomy. If the `reference_product_id` is found, its stored category takes precedence.

## Further documentation

The full documentation for creating calculations is on [this page](/api-reference/endpoint/calculations).