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

# Create a calculation

> Quote the tax for a cart. Returns a Calculation object.

Quotes tax for a cart at checkout. The response is a [Calculation object](https://docs.numeral.com/v2026-11-01/objects/calculations.md#the-calculation-object); use its `id` to [create a transaction](https://docs.numeral.com/api-reference/v2026-11-01/endpoint/transactions) once the customer pays.

> [!NOTE]
>
> **New in 2026-11-01:** every `tax_jurisdictions` row has a [`note`](https://docs.numeral.com/v2026-11-01/objects/calculations#notes), and the response has an [`effective_tax_rate`](https://docs.numeral.com/v2026-11-01/objects/calculations#effective-tax-rate). The request is unchanged from `2026-03-01`.

### Headers

**Authorization** `string` *required*

Your API key, as `Bearer <key>`.

**X-API-Version** `string` *required*

API version. Overrides your account's default version for this request.

### Body

**customer** `object` *required*

Who is buying. At least one of `customer.address` or `customer.ip` is required.

**address** `object`

Destination address. Optional when `ip` is sent; with both, the address is used and the IP is the fallback.

**address\_line\_1** `string`

**address\_line\_2** `string`

**address\_city** `string`

**address\_province** `string`

ISO 3166-2 subdivision code. Always send it for US addresses.

**address\_postal\_code** `string`

**address\_country** `string`

ISO 3166-1 alpha-2 country code.

**address\_type** `string`

`shipping` or `billing`. Only valid on `customer.address`.

**ip** `object`

IP address for location lookup when you don't have a full address. See [IP-based tax resolution](https://docs.numeral.com/v2026-11-01/objects/calculations.md#ip-based-tax-resolution).

**value** `string` *required*

A valid IPv4 or IPv6 address.

**resolution** `string` (default: strict)

What to do when the IP can't be resolved precisely enough: `strict` (error), `zero` (zero-rate response), `approximate`, or `best_effort`.

**id** `string`

ID of a customer you created in Numeral. Used for exemptions.

**type** `string` (default: CONSUMER)

`CONSUMER` or `BUSINESS`.

**tax\_ids** `object[]`

Required when `type` is `BUSINESS` and the address is outside the US. Not allowed for `CONSUMER`.

**type** `string` *required*

Tax ID type, e.g. `eu_vat`, `gb_vat`, `au_abn`. See [tax IDs](https://docs.numeral.com/essentials/tax-ids.md).

**value** `string` *required*

The tax ID.

**skip\_tax\_id\_validation** `boolean` (default: false)

Skip format and registry checks on `tax_ids`.

**order\_details** `object` *required*

The cart.

**customer\_currency\_code** `string` *required*

ISO 4217 currency code. See [supported currencies](https://docs.numeral.com/essentials/currencies.md).

**tax\_included\_in\_amount** `boolean` *required*

Whether line item amounts already include tax. Usually `false` in North America.

**automatic\_tax** `string` *required*

`auto` returns real rates where you're registered. `disabled` always returns 0. Must be `auto` for US addresses.

**line\_items** `object[]` *required*

One entry per product. Each needs `reference_product_id` or `product_category`.

**amount** `integer` *required*

**Per-unit** price in the currency's smallest unit. Taxable base is `amount × quantity`.

**quantity** `integer` *required*

Quantity sold.

**product\_category** `string`

Tax category from the [category list](https://docs.numeral.com/essentials/product-categories.md). Required if no `reference_product_id`.

**reference\_product\_id** `string`

Your product ID, as created in Numeral. Required if no `product_category`.

**fallback\_product\_category** `string`

Used when `reference_product_id` isn't found in Numeral, instead of returning an error.

**reference\_line\_item\_id** `string`

Your line item ID, echoed back for record keeping.

**origin\_address** `object`

Ship-from address. Required unless a default origin is set for the destination on your account.

**address\_line\_1** `string`

**address\_line\_2** `string`

**address\_city** `string`

**address\_province** `string`

ISO 3166-2 subdivision code.

**address\_postal\_code** `string`

**address\_country** `string`

ISO 3166-1 alpha-2 country code.

**transacted\_at** `integer`

When the sale happened, Unix **seconds**. Rates and rules are evaluated as of this time. Defaults to now.

**default\_customer\_type** `string`

`CONSUMER` or `BUSINESS`. Used when `customer.id` isn't found in Numeral, instead of returning an error.

**invalid\_tax\_id\_customer\_fallback\_type** `string`

`CONSUMER`. Treat the customer as a consumer when tax ID validation fails, instead of returning a 400.

**metadata** `object`

String key-value pairs (values up to 255 characters), echoed back in the response.

### Returns

A [Calculation object](https://docs.numeral.com/v2026-11-01/objects/calculations.md#the-calculation-object). Errors are listed on the [Calculations page](https://docs.numeral.com/v2026-11-01/objects/calculations.md#errors).

```json 200 theme={null}
{
  "testmode": true,
  "id": "calc_1793039299123",
  "object": "tax.calculation",
  "customer_currency_code": "USD",
  "line_items": [
    {
      "line_item_id": "li_1793039299101",
      "product": {
        "reference_line_item_id": "widget",
        "reference_product_id": "default-general-merchandise",
        "reference_product_name": "Default GENERAL_MERCHANDISE Product",
        "product_tax_code": "GENERAL_MERCHANDISE"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.0625,
          "tax_due_decimal": 625,
          "fee_amount": 0,
          "rate_type": "GENERAL STATE SALES TAX",
          "tax_authority_name": "Illinois",
          "tax_authority_type": "",
          "tax_type": "SALES",
          "note": ""
        },
        {
          "tax_rate": 0.03,
          "tax_due_decimal": 300,
          "fee_amount": 0,
          "rate_type": "GENERAL COUNTY LOCAL SALES TAX",
          "tax_authority_name": "Cook County",
          "tax_authority_type": "",
          "tax_type": "SALES",
          "note": ""
        },
        {
          "tax_rate": 0.0125,
          "tax_due_decimal": 125,
          "fee_amount": 0,
          "rate_type": "GENERAL CITY LOCAL SALES TAX",
          "tax_authority_name": "Chicago",
          "tax_authority_type": "",
          "tax_type": "SALES",
          "note": ""
        }
      ],
      "tax_amount": 1050,
      "amount_excluding_tax": 10000,
      "amount_including_tax": 11050,
      "quantity": 2
    },
    "... shipping line, tax_amount 105 on 1000 ..."
  ],
  "total_tax_amount": 1155,
  "tax_included_in_amount": false,
  "total_amount_excluding_tax": 11000,
  "total_amount_including_tax": 12155,
  "expires_at": 1793125699,
  "customer": {
    "type": "CONSUMER"
  },
  "automatic_tax": "auto",
  "address_resolution_status": "EXACT",
  "address_used": {
    "address_line_1": "233 S Wacker Dr",
    "address_city": "Chicago",
    "address_province": "IL",
    "address_postal_code": "60606",
    "address_country": "US"
  },
  "location_source": "address",
  "resolution_precision": "STREET",
  "effective_tax_rate": 0.105
}
```

```json 400 theme={null}
{
  "code": 400,
  "type": "MISSING_FIELD",
  "message": "Field 'order_details.automatic_tax' is required"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.