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