Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.commenda.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The /calculate endpoint allows you to determine the amount of indirect tax to charge on a transaction. By providing details such as customer information, line items, and pricing, you’ll receive accurate tax calculations based on applicable jurisdictions and rates.

​
Supported countries

The calculation engine currently supports the following countries:
CountryCodeShip-from address required
United StatesUSNo
United KingdomGBYes
For UK (GB) calculations, you must include a ship_from address in your request. If omitted, the API returns a 400 error.

​
Address validation

When you submit a calculation request, the API validates your addresses against the destination country’s requirements. Only country is required at the schema level for all addresses. Other fields such as postal_code and state are conditionally required depending on the destination country. For example, US addresses require both postal_code and state, while GB addresses require postal_code but treat state as optional. You can look up which fields are required for a given country using the address requirements endpoint before making a calculation request.

​
Factors affecting tax rates

Our system considers the following factors to determine the appropriate tax for a transaction:
  1. Seller Information
    • State Registrations:
      • If your corporation is not registered to pay taxes in a state, the /calculate endpoint will return a tax amount of 0 for that state.
      • If your corporation is registered in a state, we calculate the tax amount based on that state’s rates and rules.
  2. Product-Specific Information
    • Product Taxability:
      • Product Configuration: Each corporation can define and manage its product catalog via our /products endpoints. (Coming soon)
      • Product Code Assignment: For every product in the catalog, you can assign a specific product code using the API.
      • Tax Rate Computation: When the /calculate endpoint is called, each line item includes a product id. We use this id to retrieve the pre-configured product code for that product, determining its taxability for the transaction.
        • If a product is classified as non-taxable based on its product code, the tax amount for that specific line item will be 0.
        • If a product is taxable, the tax is calculated based on the product’s price and applicable tax rates.
  3. Customer Information
    • Shipping address: We compute the tax rate based on the ship-to address provided for each transaction.
    • Ship-from address: For some countries (e.g., GB), the ship-from address is required and factors into the tax calculation.
    • Customer exemptions: Transactions can be exempted from sales tax based on properties of the customer making the purchase. You can read more about these exemptions here.

​
Address resolution and validation

The /calculate endpoint validates addresses against country-specific requirements before computing tax.

​
Ship-to address resolution

The destination address is resolved in the following order:
  1. addresses.ship_to from the request body (highest priority).
  2. Customer’s default shipping address — used when ship_to is omitted and a customer_id is provided with a shipping address on file.
  3. Error — if neither is available, the request returns a 400 error with sub-type MISSING_SHIP_TO_ADDRESS.

​
Ship-from address

The ship_from address is optional for most countries but required for certain destination countries (e.g., GB). If required but missing, the request returns a 400 error with sub-type MISSING_SHIP_FROM_ADDRESS. When a ship-from address is provided for US destinations, the state must be a valid US state code and the postal code must be a valid US ZIP format.

​
Country-specific field validation

Each address is validated against per-country requirements that define which fields are required, optional, or ignored. Only country is always required. All other fields — including postal_code and state — may be required, optional, or ignored depending on the country. Validation includes:
  • Field presence — required fields (e.g., address_line_1, city for US) must be provided and non-empty.
  • State code validation — the state must match one of the valid ISO 3166-2 subdivision codes for the country.
  • Postal code format — when a postal code is provided, it must match the country’s expected format (e.g., ^\d{5}(-\d{4})?$ for US ZIP codes). The postal_code field is required for the US, EU countries (such as DE and FR), and GB. For CA, postal_code is optional but providing it improves tax jurisdiction accuracy.
Use the /address-requirements endpoint to query which fields and formats are expected for each country before calling /calculate.

​
Multi-currency support

The /calculate endpoint supports transactions in any ISO 4217 currency. You specify the currency of your transaction using the transaction_currency field, and all monetary values in the response are returned in that same currency.

​
How it works

When you submit a calculation, the engine applies tax rates in the destination country’s local currency. If your transaction_currency differs from the destination country’s default currency, the system automatically:
  1. Converts your line item amounts into the destination country’s currency.
  2. Looks up and applies the correct tax rates in that local currency.
  3. Converts the calculated tax amounts back into your transaction_currency.
This means tax rates are always applied accurately in the jurisdiction’s native currency, regardless of the currency your transaction is denominated in.

​
Currency fields in the response

FieldDescription
transaction_currencyThe currency you specified in the request. All amounts in the response (total_amount, total_tax, total_due, and line item amounts) are expressed in this currency.
tax_currencyThe currency in which tax amounts are expressed. This matches transaction_currency.
calculation_currencyThe destination country’s default currency used internally to look up tax rates. Only present when a currency conversion occurred.
exchange_rateThe exchange rate applied between transaction_currency and calculation_currency. Only present when a currency conversion occurred.
If you omit transaction_currency from your request, it defaults to the destination country’s local currency (e.g., USD for the US, GBP for the UK, EUR for Germany).

​
Monetary value rounding

Amounts are rounded according to the ISO 4217 standard for each currency:
  • Two decimal places — most currencies (e.g., USD, EUR, GBP)
  • Zero decimal places — JPY, KRW, HUF, CLP, IDR, VND, ISK, TWD
  • Three decimal places — BHD, KWD, OMR

​
Example: cross-currency calculation

If you sell a product in EUR to a customer in the US, set transaction_currency to EUR. The engine converts the amounts to USD to calculate US sales tax, then converts the results back to EUR: 
{
  "transaction_currency": "EUR",
  "calculation_currency": "USD",
  "exchange_rate": 1.08,
  "total_amount": 100.00,
  "total_tax": 8.79,
  "total_due": 108.79
}
When both the transaction and destination use the same currency (e.g., USD transaction to a US address), no conversion occurs and calculation_currency and exchange_rate are omitted.

​
Sample calculation object

The /calculate endpoint returns a JSON object containing the transaction details and calculated taxes. Example response: 
{
  "data": {
    "id": "a7850851-be24-4c71-b9a3-3035e2d0c617",
    "corporation_id": "74df772f-9260-42cf-9c20-3b613b60fecd",
    "transaction_date": "2025-07-01",
    "transaction_currency": "USD",
    "discount": 0,
    "total_amount": 14338.01,
    "total_tax": 1190.05,
    "total_due": 15528.06,
    "customer_details": {},
    "tax_currency": "USD",
    "addresses": {
      "ship_from": null,
      "ship_to": {
        "address_line_1": "123 N Central Ave",
        "address_line_2": "",
        "address_line_3": "",
        "postal_code": "85004",
        "city": "Phoenix city",
        "state": "AZ",
        "country": "US"
      }
    },
    "line_items": [
      {
        "line_item_id": "51f4ac30-e4f6-42e9-bb34-80305ea870b2",
        "amount": 14338.01,
        "taxable_amount": 14338.01,
        "quantity": 1,
        "tax_code": "TPP",
        "product_id": "",
        "line_number": 1,
        "effective_tax_rate": 8.3,
        "base_tax_rate": 9.1,
        "tax_breakdown": [
          {
            "jurisdiction_name": "ARIZONA",
            "jurisdiction_type": "STATE_OR_PROVINCE",
            "rate": 5.6,
            "base_rate": 5.6,
            "tax_class": "TAXABLE",
            "tax_class_reason": "TAX_APPLIED"
          },
          {
            "jurisdiction_name": "MARICOPA COUNTY",
            "jurisdiction_type": "COUNTY",
            "rate": 0.7,
            "base_rate": 0.7,
            "tax_class": "TAXABLE",
            "tax_class_reason": "TAX_APPLIED"
          },
          {
            "jurisdiction_name": "PHOENIX CITY",
            "jurisdiction_type": "CITY",
            "rate": 2,
            "base_rate": 2.8,
            "tax_class": "TAXABLE",
            "tax_class_reason": "TAX_APPLIED"
          }
        ],
        "total_tax_due": 1190.05,
        "tax_collected": 0,
        "is_tax_included": false,
        "product_source_platform": "",
        "product_source_platform_id": ""
      }
    ]
  }
}