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.

How to create Calculations

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
      }
    ]
  }
}'

Sample Response

{
  "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"
}

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.

Caution about simply summing tax_rate values. Each tax_rate in tax_jurisdictions is the statutory rate for that jurisdiction, and in some jurisdictions a rate applies to only part of the line item amount. Tennessee’s single article rules are the common example: local rates apply only to the first $1,600 of an item, and the 2.75% state single article rate applies only to the portion between $1,600 and $3,200. For a $10,000 item the returned rates sum to 12.25%, but the tax due is $788, an effective rate of 7.88%.

Always charge the returned tax_amount (or total_tax_amount). If you need an effective rate, compute tax_amount / amount_excluding_tax from the response rather than adding up tax_rate values. Jurisdictions whose rate applies to only part of the amount carry a note value other than RATE_FRAC, such as PROGRESSIVE_RATE.

Request Parameters

Customer Object

{
  "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

{
  "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.