Tax Calculation

The service 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
}