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

> Quote the tax for a cart at checkout

A calculation quotes the tax for a cart. Create one at checkout after the customer enters an address and before you take payment. Use its `id` to record a [transaction](https://docs.numeral.com/v2026-11-01/objects/transactions.md) once the customer pays.

```text Where calculations fit in checkout theme={null}
Checkout
├─ 1. Customer enters checkout
├─ 2. Customer enters address
│     └─ POST /tax/calculations
│          send:    products + address
│          receive: tax + calculation id
├─ 3. Tax added to the order total
└─ 4. Customer completes the purchase
      └─ POST /tax/transactions
           send:    calculation id
           receive: transaction id
```

Endpoints
[Create a calculationPOST/tax/calculations](#create-a-calculation)

## The Calculation object

### Attributes

**id** `string`

The ID of the calculation. Use it to create a transaction.

**object** `string, value is "tax.calculation"`

String representing the object's type.

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

ISO 4217 currency code of the calculation.

**line\_items** `array of objects`

One entry per line item in the request, in the same order.

**line\_items\[].line\_item\_id** `string`

Numeral-generated ID for this line item. Use it to reference the line in refunds.

**line\_items\[].product** `object`

Product information for this line item.

**line\_items\[].product.reference\_line\_item\_id** `string`

Echo of the `reference_line_item_id` you sent.

**line\_items\[].product.reference\_product\_id** `string`

The product ID in your system. `default-<category>` when the line was sent with `product_category`.

**line\_items\[].product.reference\_product\_name** `string`

The name of the product.

**line\_items\[].product.product\_tax\_code** `string`

The product category used to decide taxability.

**line\_items\[].tax\_jurisdictions** `array of objects`

One row per taxing jurisdiction. Empty when no tax applies, for example in states with no sales tax.

**line\_items\[].tax\_jurisdictions\[].tax\_rate** `number`

Statutory rate for the jurisdiction, as a decimal fraction (`0.0625` = 6.25%). Doesn't include flat fees. Some rates apply to only part of the amount, so don't sum these; use [`effective_tax_rate`](#effective-tax-rate).

**line\_items\[].tax\_jurisdictions\[].tax\_due\_decimal** `number`

Unrounded tax due for this jurisdiction, in the currency's smallest unit.

**line\_items\[].tax\_jurisdictions\[].fee\_amount** `number`

Flat fee charged by this jurisdiction, in the currency's smallest unit. `0` on rate-based rows.

**line\_items\[].tax\_jurisdictions\[].rate\_type** `string`

Name of the tax, e.g. `GENERAL STATE SALES TAX`.

**line\_items\[].tax\_jurisdictions\[].tax\_authority\_name** `string`

Taxing jurisdiction, e.g. `Illinois` or `Cook County`.

**line\_items\[].tax\_jurisdictions\[].tax\_authority\_type** `string`

Type of authority. Often empty; `Country` on some international rows.

**line\_items\[].tax\_jurisdictions\[].tax\_type** `enum`

`SALES`, `USE`, `VAT`, `GST`, or `PST`.

**line\_items\[].tax\_jurisdictions\[].note** `string`

**New in 2026-11-01.** Why this row came out the way it did. Empty string for normally calculated tax. See [Notes](#notes) for every value.

**line\_items\[].tax\_amount** `integer`

Tax for this line item, in the currency's smallest unit.

**line\_items\[].amount\_excluding\_tax** `integer`

Line amount before tax (`amount × quantity`). When `tax_included_in_amount` is `true`, the tax is backed out of the amount you sent.

**line\_items\[].amount\_including\_tax** `integer`

`amount_excluding_tax + tax_amount`.

**line\_items\[].quantity** `number`

Echo of the quantity you sent.

**total\_tax\_amount** `integer`

Total tax to charge, in the currency's smallest unit.

**total\_amount\_excluding\_tax** `integer`

Total excluding tax, in the currency's smallest unit.

**total\_amount\_including\_tax** `integer`

Total including tax. What you charge your customer.

**effective\_tax\_rate** `number`

**New in 2026-11-01.** `total_tax_amount / total_amount_excluding_tax`, as a decimal fraction (`0.105` = 10.5%). Includes flat fees. See [Effective tax rate](#effective-tax-rate).

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

Echo of the request: whether line item amounts already include tax.

**automatic\_tax** `enum`

`auto` or `disabled`. Echo of the request.

**customer** `object`

The customer as used for the calculation.

**customer.type** `enum`

`CONSUMER` or `BUSINESS`. The type actually used, which can fall back to `CONSUMER` when a business tax ID fails validation.

**customer.tax\_ids** `array of objects`

Echo of the `tax_ids` you sent, when present. Each has `type` (e.g. `eu_vat`) and `value`.

**address\_resolution\_status** `enum`

How precisely the address matched: `EXACT`, `POSTAL_FALLBACK_1`, or `POSTAL_ONLY`.

**address\_used** `object`

The address the tax was calculated for.

**address\_used.address\_line\_1** `string`

**address\_used.address\_line\_2** `string`

Only present when there is one.

**address\_used.address\_city** `string`

**address\_used.address\_province** `string`

ISO 3166-2 subdivision code.

**address\_used.address\_postal\_code** `string`

**address\_used.address\_country** `string`

ISO 3166-1 alpha-2 country code.

**location\_source** `enum`

`address` or `ip`: which input set the location.

**resolution\_precision** `enum`

`STREET`, `POSTAL_PLUS`, `POSTAL`, `PROVINCE`, `COUNTRY`, or `APPROXIMATED`.

**expires\_at** `timestamp`

Unix seconds when the quoted rates expire, 24 hours after creation.

**testmode** `boolean`

`true` if made with a test API key.

**metadata** `object`

Key-value pairs from the request, echoed unchanged. Only present when sent.

```json The Calculation object 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
    },
    {
      "line_item_id": "li_1793039299102",
      "product": {
        "reference_line_item_id": "shipping",
        "reference_product_id": "default-shipping",
        "reference_product_name": "Default SHIPPING Product",
        "product_tax_code": "SHIPPING"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.0625,
          "tax_due_decimal": 62.5,
          "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": 30,
          "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": 12.5,
          "fee_amount": 0,
          "rate_type": "GENERAL CITY LOCAL SALES TAX",
          "tax_authority_name": "Chicago",
          "tax_authority_type": "",
          "tax_type": "SALES",
          "note": ""
        }
      ],
      "tax_amount": 105,
      "amount_excluding_tax": 1000,
      "amount_including_tax": 1105,
      "quantity": 1
    }
  ],
  "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
}
```

## Notes

Every `tax_jurisdictions` row has a `note`. It's an empty string when tax was calculated normally. Otherwise it tells you why the row came out the way it did, so a 0 is never a mystery.

| `note` | Meaning |
| - | - |
| `""` | Tax was calculated normally for this jurisdiction. |
| `no_collection_exempt_customer` | No tax collected: the customer is tax exempt, for everything or through an exemption certificate that covers this item. US and Canada only. |
| `no_collection_no_state_nexus` | No tax collected: you have no tax registration set up for this US state or Canadian province. |
| `no_collection_no_vat_registration` | No tax collected: you have no VAT registration set up for this country. |
| `no_collection_no_gst_registration` | No tax collected: you have no GST registration set up for this country (Australia, New Zealand, India, Singapore). |
| `collection_manually_deactivated` | No tax collected: you have a registration for this jurisdiction but turned collection off. |
| `automatic_tax_disabled` | No tax collected: the request sent `automatic_tax: "disabled"`. |
| `b2b_reverse_charge` | No tax collected: a cross-border business-to-business sale where the buyer accounts for the tax (reverse charge). |
| `shipping_follows_highest_taxed_item` | The shipping line is taxed at the highest VAT rate of the other items in the order (UK). |
| `canary_islands_zero_rate` | No VAT: the Canary Islands are outside the EU VAT area. |

* All rows on one line item share the same note. Different line items can have different notes, for example a UK order's goods line (`""`) and shipping line (`shipping_follows_highest_taxed_item`).
* A line item with no rows (`tax_jurisdictions: []`) has no note.
* Test API keys skip registration checks by default, so `no_collection_no_state_nexus`, `no_collection_no_vat_registration`, `no_collection_no_gst_registration` and `collection_manually_deactivated` normally show up only on live calls.
* Records created before this version was released may return an empty note.

```json Exempt customer theme={null}
{
  "tax_rate": 0,
  "tax_due_decimal": 0,
  "fee_amount": 0,
  "rate_type": "Sales Tax",
  "tax_authority_name": "State Tax",
  "tax_authority_type": "",
  "tax_type": "SALES",
  "note": "no_collection_exempt_customer"
}
```

```json Reverse charge theme={null}
{
  "tax_rate": 0,
  "tax_due_decimal": 0,
  "fee_amount": 0,
  "rate_type": "VAT",
  "tax_authority_name": "FR",
  "tax_authority_type": "Country",
  "tax_type": "VAT",
  "note": "b2b_reverse_charge"
}
```

```json UK shipping line theme={null}
{
  "tax_rate": 0.2,
  "tax_due_decimal": 400,
  "fee_amount": 0,
  "rate_type": "VAT",
  "tax_authority_name": "GB",
  "tax_authority_type": "Country",
  "tax_type": "VAT",
  "note": "shipping_follows_highest_taxed_item"
}
```

```json Canary Islands theme={null}
{
  "tax_rate": 0,
  "tax_due_decimal": 0,
  "fee_amount": 0,
  "rate_type": "VAT",
  "tax_authority_name": "Canary Islands",
  "tax_authority_type": "",
  "tax_type": "VAT",
  "note": "canary_islands_zero_rate"
}
```

```json Automatic tax disabled theme={null}
{
  "tax_rate": 0,
  "tax_due_decimal": 0,
  "fee_amount": 0,
  "rate_type": "VAT",
  "tax_authority_name": "Jurisdiction VAT",
  "tax_authority_type": "",
  "tax_type": "VAT",
  "note": "automatic_tax_disabled"
}
```

## Effective tax rate

`effective_tax_rate` is the whole order's tax as one rate:

```text theme={null}
effective_tax_rate = total_tax_amount / total_amount_excluding_tax
```

* Both amounts are the rounded totals in the same response.
* Decimal fraction (`0.077407` = 7.7407%), up to 6 decimal places, rounded half-up.
* Includes flat fees, such as Minnesota's retail delivery fee. Row `tax_rate` values don't, so `effective_tax_rate` can be higher than their sum.
* Can be lower than the sum of row rates when a rate applies to only part of the amount. Tennessee's single article rules are the common case.
* With `tax_included_in_amount: true`, the denominator is the amount with tax backed out: €119.00 including 19% VAT gives `1900 / 10000 = 0.19`.
* `0` when no tax applies, including exempt customers, `automatic_tax: "disabled"`, and zero-rate IP responses.
* There's no per-line rate field. For one line, divide its `tax_amount` by its `amount_excluding_tax`.

Always charge `total_tax_amount`. Use `effective_tax_rate` for display and reporting.

```json Tennessee single article theme={null}
{
  "line_items": [
    {
      "product": {
        "reference_line_item_id": "annual-license",
        "product_tax_code": "SAAS_GENERAL"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.0275,
          "tax_due_decimal": 4400,
          "rate_type": "SINGLE_ARTICLE STATE SALES TAX",
          "tax_authority_name": "Tennessee",
          "note": ""
        },
        {
          "tax_rate": 0.07,
          "tax_due_decimal": 75600,
          "rate_type": "GENERAL STATE SALES TAX",
          "tax_authority_name": "Tennessee",
          "note": ""
        },
        {
          "tax_rate": 0.0225,
          "tax_due_decimal": 3600,
          "rate_type": "SINGLE_ARTICLE CITY LOCAL SALES TAX",
          "tax_authority_name": "Place 40000, TN",
          "note": ""
        }
      ],
      "tax_amount": 83600,
      "amount_excluding_tax": 1080000
    }
  ],
  "total_tax_amount": 83600,
  "total_amount_excluding_tax": 1080000,
  "effective_tax_rate": 0.077407
}
```

```json Minnesota delivery fee theme={null}
{
  "line_items": [
    {
      "product": { "product_tax_code": "SHIPPING" },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.06875,
          "tax_due_decimal": 68.75,
          "fee_amount": 0,
          "rate_type": "GENERAL STATE SALES TAX",
          "note": ""
        },
        {
          "tax_rate": 0,
          "tax_due_decimal": 0,
          "fee_amount": 50,
          "rate_type": "ROAD_IMPROVEMENT_AND_FOOD_DELIVERY_FEE STATE SALES TAX",
          "note": ""
        },
        "... 5 local rows ..."
      ],
      "tax_amount": 140,
      "amount_excluding_tax": 1000
    },
    "... goods line, tax_amount 1264 on 14000 ..."
  ],
  "total_tax_amount": 1404,
  "total_amount_excluding_tax": 15000,
  "effective_tax_rate": 0.0936
}
```

The Tennessee rows sum to 12%, but local tax applies only to the first $1,600 and the 2.75% single article tax only to the $1,600–$3,200 band, so $10,800 is taxed \$836.

## Create a calculation

Quotes tax for a cart. Send `X-API-Version` on every request. [Try it in the API reference](https://docs.numeral.com/api-reference/v2026-11-01/endpoint/calculations).

### Parameters

**customer** `object` *required*

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

**customer.address** `object`

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

**customer.address.address\_line\_1** `string`

**customer.address.address\_line\_2** `string`

**customer.address.address\_city** `string`

**customer.address.address\_province** `string`

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

**customer.address.address\_postal\_code** `string`

**customer.address.address\_country** `string`

ISO 3166-1 alpha-2 country code.

**customer.address.address\_type** `enum`

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

**customer.ip** `object`

IP address for location lookup when you don't have a full address. See [IP-based tax resolution](#ip-based-tax-resolution).

**customer.ip.value** `string` *required*

A valid IPv4 or IPv6 address.

**customer.ip.resolution** `enum` (default: strict)

What to do when the IP can't be resolved precisely enough: `strict`, `zero`, `approximate`, or `best_effort`.

**customer.id** `string`

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

**customer.type** `enum` (default: CONSUMER)

`CONSUMER` or `BUSINESS`.

**customer.tax\_ids** `array of objects`

Required when `type` is `BUSINESS` and the address is outside the US. Not allowed for `CONSUMER`. Each has `type` (e.g. `eu_vat`, `gb_vat`, `au_abn`) and `value`. See [tax IDs](https://docs.numeral.com/essentials/tax-ids.md).

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

Skip format and registry checks on `tax_ids`.

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

The cart.

**order\_details.customer\_currency\_code** `string` *required*

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

**order\_details.tax\_included\_in\_amount** `boolean` *required*

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

**order\_details.automatic\_tax** `enum` *required*

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

**order\_details.line\_items** `array of objects` *required*

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

**order\_details.line\_items\[].amount** `integer` *required*

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

**order\_details.line\_items\[].quantity** `integer` *required*

Quantity sold.

**order\_details.line\_items\[].product\_category** `string`

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

**order\_details.line\_items\[].reference\_product\_id** `string`

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

**order\_details.line\_items\[].fallback\_product\_category** `string`

Used when `reference_product_id` isn't found in Numeral, instead of returning an error. If the product is found, its stored category wins.

**order\_details.line\_items\[].reference\_line\_item\_id** `string`

Your line item ID, echoed back for record keeping.

**origin\_address** `object`

Ship-from address, used for origin-based sourcing. Required unless a default origin is set for the destination on your account. Same fields as `customer.address`, without `address_type`.

**transacted\_at** `integer`

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

**default\_customer\_type** `enum`

`CONSUMER` or `BUSINESS`. Used when `customer.id` isn't found in Numeral, instead of returning an error. If the customer is found, its stored type wins. `BUSINESS` on a non-US address still needs `customer.tax_ids`.

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

`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](#the-calculation-object).

```bash POST /tax/calculations theme={null}
curl https://api.numeralhq.com/tax/calculations \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-11-01' \
  -d '{
    "customer": {
      "type": "CONSUMER",
      "address": {
        "address_line_1": "233 S Wacker Dr",
        "address_city": "Chicago",
        "address_province": "IL",
        "address_postal_code": "60606",
        "address_country": "US",
        "address_type": "shipping"
      }
    },
    "origin_address": {
      "address_line_1": "3990 N County Rd 300 E",
      "address_city": "Danville",
      "address_province": "IN",
      "address_postal_code": "46122",
      "address_country": "US"
    },
    "order_details": {
      "customer_currency_code": "USD",
      "tax_included_in_amount": false,
      "automatic_tax": "auto",
      "line_items": [
        {
          "reference_line_item_id": "widget",
          "product_category": "GENERAL_MERCHANDISE",
          "amount": 5000,
          "quantity": 2
        },
        {
          "reference_line_item_id": "shipping",
          "product_category": "SHIPPING",
          "amount": 1000,
          "quantity": 1
        }
      ]
    }
  }'
```

```json Response theme={null}
{
  "id": "calc_1793039299123",
  "object": "tax.calculation",
  "total_tax_amount": 1155,
  "total_amount_excluding_tax": 11000,
  "total_amount_including_tax": 12155,
  "effective_tax_rate": 0.105,
  "...": "see The Calculation object"
}
```

## IP-based tax resolution

Send `customer.ip` instead of (or with) `customer.address` when you don't have a full address, for example for digital goods. With both, the address is used and the IP is the fallback.

| `resolution` | When the IP can't be resolved precisely enough |
| - | - |
| `strict` (default) | Returns a 422 error. |
| `zero` | Returns a zero-rate calculation. |
| `approximate` | Resolves the IP to an address using heuristics. |
| `best_effort` | Tries `approximate`, then falls back to zero rates. |

> [!WARNING]
>
> Numeral strongly recommends `strict` mode to stay as compliant as possible.

A zero-rate response has `tax_jurisdictions: []` on every line (so no `note`), empty `product` fields, and `effective_tax_rate: 0`. `location_source` is `ip`, and `resolution_precision` shows how far the IP resolved.

```bash IP request theme={null}
curl https://api.numeralhq.com/tax/calculations \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-11-01' \
  -d '{
    "customer": {
      "type": "CONSUMER",
      "ip": { "value": "8.8.8.8", "resolution": "best_effort" }
    },
    "origin_address": {
      "address_line_1": "3990 N County Rd 300 E",
      "address_city": "Danville",
      "address_province": "IN",
      "address_postal_code": "46122",
      "address_country": "US"
    },
    "order_details": {
      "customer_currency_code": "USD",
      "tax_included_in_amount": false,
      "automatic_tax": "auto",
      "line_items": [
        { "reference_line_item_id": "goods", "product_category": "GENERAL_MERCHANDISE", "amount": 10000, "quantity": 1 }
      ]
    }
  }'
```

```json Zero-rate response theme={null}
{
  "id": "calc_1793039301456",
  "testmode": true,
  "object": "tax.calculation",
  "customer_currency_code": "USD",
  "tax_included_in_amount": false,
  "line_items": [
    {
      "line_item_id": "li_1793039301420",
      "quantity": 1,
      "product": {
        "reference_line_item_id": "",
        "reference_product_name": "",
        "reference_product_id": "",
        "product_tax_code": ""
      },
      "tax_jurisdictions": [],
      "tax_amount": 0,
      "amount_excluding_tax": 10000,
      "amount_including_tax": 10000
    }
  ],
  "total_tax_amount": 0,
  "total_amount_excluding_tax": 10000,
  "total_amount_including_tax": 10000,
  "expires_at": 1793125701,
  "customer": { "type": "CONSUMER" },
  "automatic_tax": "auto",
  "address_resolution_status": "POSTAL_ONLY",
  "address_used": {
    "address_line_1": "",
    "address_line_2": "",
    "address_city": "",
    "address_province": "",
    "address_postal_code": "",
    "address_country": "US"
  },
  "location_source": "ip",
  "resolution_precision": "COUNTRY",
  "effective_tax_rate": 0
}
```

## Errors

Errors return `code`, `type`, and `message`. Handle them by `type`. Full list in [Error Codes](https://docs.numeral.com/api-reference/v2026-11-01/error-codes.md).

| HTTP | `type` | When |
| - | - | - |
| 400 | `MISSING_FIELD` | A required field is missing. |
| 400 | `INCORRECT_TYPE` | A field has the wrong type. |
| 400 | `UNRECOGNIZED_FIELD` | An unknown field was sent, e.g. `address_type` on `origin_address`. |
| 400 | `POSITIVE_NUMBER_REQUIRED` | `amount` or `quantity` isn't positive. |
| 400 | `MALFORMED_ADDRESS` | Address is invalid or incomplete, or a US ZIP can't be matched to a state. |
| 400 | `ZIP_STATE_MISMATCH` | Postal code doesn't match `address_province`. |
| 400 | `MISSING_ORIGIN_ADDRESS` | No `origin_address` and no default origin for the destination. |
| 400 | `INVALID_COUNTRY_CODE` | Country isn't ISO 3166-1 alpha-2. |
| 400 | `INVALID_CURRENCY_CODE` | Currency isn't supported. |
| 400 | `INVALID_PRODUCT_CATEGORY` | `product_category` isn't in the taxonomy. |
| 400 | `INVALID_IP_FORMAT` | `customer.ip.value` isn't a valid IPv4 or IPv6 address. |
| 404 | `PRODUCT_NOT_FOUND` | `reference_product_id` doesn't exist and no `fallback_product_category` was sent. |
| 404 | `CUSTOMER_NOT_FOUND` | `customer.id` doesn't exist and no `default_customer_type` was sent. |
| 422 | `IP_RESOLUTION_FAILED` | IP couldn't be resolved to a country (`strict` mode). |
| 422 | `IP_RESOLUTION_INSUFFICIENT_US` | IP resolved to a US state but no postal code. |
| 422 | `IP_RESOLUTION_INSUFFICIENT_CA` | IP resolved to Canada but no province. |

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

```json 404 theme={null}
{
  "code": 404,
  "type": "PRODUCT_NOT_FOUND",
  "message": "Product not found"
}
```

```json 422 theme={null}
{
  "code": 422,
  "type": "IP_RESOLUTION_INSUFFICIENT_US",
  "message": "IP address resolved to US-GA but could not determine a postal code. Please provide customer.address with address_postal_code and address_province."
}
```


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