Taxamo

The Taxamo Developer Hub

Welcome to the Taxamo developer hub. You'll find comprehensive guides and documentation to help you start working with Taxamo as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

Tax Calculation

Taxamo provides location determination and tax calculation via the stand-alone /tax/calculate API endpoint and also via the /transactions API endpoint.

Product taxability

For US transactions, the product_tax_code is a required field for each line item as the product type may determine which taxes and tax rates apply.

Jurisdiction determination

Along with the product_tax_code you must provide the 2-digit state code and Zip Code in the invoice_address.region and invoice_address.postal_code fields. When possible a Zip+4 should be used to ensure the most accurate jurisdiction determination. The Address Validation service can be used to determine the Zip+4 from a street address.

Tax components

As well as overall and per transaction-line tax rates and amounts, the result includes an overall and transaction-line level breakdown into the individual taxes which are applied. As shown in the example below, state, country, city, and other taxes are stated individually in the tax_components array in the transaction object and in each transaction line. Tax reports also include this level of detail.

{
    "transaction": {
        "currency_code": "USD",
        "transaction_lines": [
            {
                "custom_id": "1",
                "amount": 100,
                "product_type":"default",
                "product_tax_code": "310108"
            }
        ],
        "billing_country_code": "US",
        "invoice_address": {
            "street_name": "10 Pine St",
              "city": "Seattle",
              "region": "WA",
              "postal_code": "98103", 
            "country":"US"},
        "buyer_name":"California",
        "buyer_ip": "72.229.28.185"
    },
    "private_token": "priv_test_36gHlrdp5ULnpkerpzYLGLTE4jp2TXswZ6QS3B_QJnE"
}
{
    "transaction": {
        "amount": 100.0,
        "invoice_address": {
            "street_name": "10 Pine St",
            "city": "Seattle",
            "region": "WA",
            "postal_code": "98103",
            "country": "US",
            "used_for_tax_calculation": true,
            "lookup_result": {
                "found": true,
                "score": 1,
                "found_data": {
                    "street_name": "10 PINE ST",
                    "city": "SEATTLE",
                    "postal_code": "98101+1531",
                    "county": "KING",
                    "state": "WA"
                },
                "cached": true
            }
        },
        "external_key": "jB1QxcaAVJ-U1JhB",
        "tax_country_codes": "US",
        "tax_amount": 10.1,
        "tax_deducted": false,
        "tax_region": "US",
        "billing_country_code": "US",
        "evidence": {
            "by_ip": {
                "evidence_value": "72.229.28.185",
                "used": true,
                "resolved_country_code": "US",
                "evidence_type": "by-ip"
            },
            "by_billing": {
                "evidence_value": "US",
                "used": true,
                "resolved_country_code": "US",
                "evidence_type": "by-billing"
            }
        },
        "tax_country_code": "US",
        "countries": {
            "by_ip": {
                "tax_region": "US",
                "tax_supported": true,
                ...
            },
            "by_billing": {
                "tax_region": "US",
                "tax_supported": true,
                ...
            },
            "detected": {
                "tax_region": "US",
                "tax_supported": true,
                ...
            }
        },
        "transaction_lines": [
            {
                "amount": 100.0,
                "unit_price": 100.0,
                "tax_amount": 10.1,
                "tax_deducted": false,
                "tax_region": "US",
                "cached_rate": false,
                "tax_rate": 10.1,
                "additional_currencies": {
                    "tax": {
                        "currency_code": "USD",
                        "amount": 100.0,
                        "total_amount": 110.1,
                        "unit_price": 100.0,
                        "fx_rate": 1,
                        "tax_amount": 10.1
                    }
                },
                "tax_country_code": "US",
                "line_key": "PEyhWd4CjKNolPur",
                "custom_id": "1",
                "product_type": "default",
                "tax_name": "WA Tax",
                "product_tax_code": "310108",
                "line_num": 1,
                "quantity": 1,
                "total_amount": 110.1,
                "tax_components": [
                    {
                        "tax_rate": 6.5,
                        "tax_amount": 6.5,
                        "state_code": "WA",
                        "tax_name": "STATE SALES TAX",
                        "tax_authority_id": "12047",
                        "tax_authority_name": "WASHINGTON, STATE OF",
                        "jurisdiction_code": "",
                        "percent_taxable": 1.0
                    },
                    {
                        "tax_rate": 3.6,
                        "tax_amount": 3.6,
                        "state_code": "WA",
                        "tax_name": "COUNTY SALES TAX",
                        "tax_authority_id": "10552",
                        "tax_authority_name": "KING, COUNTY OF",
                        "jurisdiction_code": "1726",
                        "percent_taxable": 1.0
                    }
                ],
                "tax_entity_name": "US",
                "tax_supported": true
            }
        ],
        "buyer_ip": "72.229.28.185",
        "refunded_tax_amount": 0,
        "force_country_code": null,
        "country_name": "United States",
        "product_classes": "D",
        "fully_informative": false,
        "kind": "us-b2c",
        "refunded_total_amount": 0,
        "order_date_type": "timestamp",
        "shipment_country_data": {},
        "buyer_name": "California",
        "deducted_tax_amount": 0,
        "order_date": "2020-04-15T08:09:14Z",
        "total_amount": 110.1,
        "tax_components": [
            {
                "tax_name": "STATE SALES TAX",
                "tax_rate": 6.5,
                "tax_amount": 6.5
            },
            {
                "tax_name": "COUNTY SALES TAX",
                "tax_rate": 3.6,
                "tax_amount": 3.6
            }
        ],
        "tax_timezone": "GMT",
        "sub_account_id": "18109",
        "tax_entity_name": "WA",
        "tax_supported": true,
        "customer_id": "rZRp6hA-VCu1yZXD",
        "currency_code": "USD"
    },
    "tax_required_fields": [
        {
            "field_name": "invoice_address.postal_code"
        }
    ],
    "storage_required_fields": [],
    "is_delegated": false
}

Updated 3 months ago


Tax Calculation


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.