Calculate Tax

You use the Calculate Tax request to retrieve a tax rate and amount that is generated by Taxamo. For example, you may use this request to calculate the tax rate in a basket before the order is confirmed or on the details page for a product.

In this sample scenario, this request is used to retrieve a tax rate from Taxamo and display it on a storefront. It is intended to emulate a scenario where a buyer wants to view the tax on some goods before completing their purchase.

The Calculate Tax request does not create a transaction key or store certain details for things like invoices. To do this, you use the Store Transaction request.

Process Flow

This diagram shows the steps for this scenario:

The process flow is as follows:

Buyer places goods in basket but does not confirm the purchase.
The buyer, Eric, visits the webstore of a small business, Angela's Smoked Herring Store. Angela (the seller) has integrated her webstore with Taxamo Assure by Vertex.
Store uses the Calculate Tax request to connect to retrieve tax from Taxamo.
Eric places 1 packet of smoked herring in his basket but does not confirm the checkout. He would like to know what the tax amount will be on his purchase. He views his cart/basket and provides the country that the order will be shipped to.
The tax rate for the basket is returned by the Taxamo API.
Angela's store uses the Calculate Tax request to retrieve the correct rate from Taxamo. It uses the details entered on the storefront to retrieve the tax rate for these goods. In the sample scenario, the following address details for the buyer and seller are also included in the information that is sent to the API.
The buyer views the tax rate in his basket on the storefront
Eric views the tax amount, rate and a total including the tax.

Request Notes

To generate a tax rate and amount, you need to add the following fields:

transaction.ship_to_address.countrycode
transaction.transaction_lines.product_cn_code

If you do not add these fields, the standard tax rate is returned.

You also need to add one of the following amount fields:

transaction.transaction_lines[].amount
transaction.transaction_lines[].total_amount

Other fields are optional and these details could be included in the other requests if so desired. These particular fields have been chosen to reflect the example above.

Response Notes

In the sample files, the €5 is the total taxable amount for 1 packet of herring. This information is provided in the JSON response that is returned by the API (in the tax_amount field). For example:

"tax_amount": 5,

The total amount including tax is also returned in the total_amount field:

"total_amount": 54.95,

Sample Request

{
"transaction": {
    "currency_code": "EUR",
    "buyer_name": "Eric Papin",
    "ship_to_address": {
      "address_detail": "Chateuax 12",
      "building_number": "55",
      "street_name": "Rue du Saint-Germain",
      "city": "Paris",
      "postal_code": "75008 ",
      "country_code": "FR"
    },
    "transaction_lines": [
      {
        "product_class": "P",
        "quantity": 1,
        "description": "Smoked herrings",
        "amount": "49.95",
        "custom_id": "51315A00-DC44-408E-A575-8CE42A32AE1B",
        "import_address":{
            "country_code": "FR"
        },
        "ship_from_address": {
            "building_number": "12",
            "street_name": "Wessex End Street",
            "city": "London",
          "postal_code": "SW1A 2AA",
          "country_code": "GB"
        },
        "product_cn_code": "0305420000"
      }
    ]
  }
}

Sample Response

{
    "transaction": {
        "ship_to_address": {
            "city": "Paris",
            "country_code": "FR",
            "postal_code": "75008 ",
            "street_name": "Rue du Saint-Germain",
            "address_detail": "Chateuax 12",
            "building_number": "55",
            "tax_region": "EU"
        },
        "amount": 49.95,
        "required_fields": {
            "tax_required_fields": [],
            "audit_required_fields": [],
            "storage_required_fields": []
        },
        "tax_country_codes": "FR",
        "tax_amount": 5,
        "invoice_timestamp": "2021-09-22T11:49:18Z",
        "tax_liability_owner_codes": "Taxamo",
        "countries": {},
        "transaction_lines": [
            {
                "description": "Smoked herrings",
                "reverse_charge": false,
                "amount": 49.95,
                "tax_rule_applied": "physical-tax",
                "unit_price": 49.95,
                "taxes": [
                    {
                        "rate": 10,
                        "tax_name": "European VAT",
                        "rate_type": "Reduced",
                        "amount_fraction_taxable": 1,
                        "tax_base_amount": 49.95
                    }
                ],
                "tax_amount": 5,
                "import_address": {
                    "country_code": "FR",
                    "tax_region": "EU"
                },
                "tax_liability_rule": "physical-shipment-into-EU-goods-below-150-eur-with-ioss-non-EU-supplier",
                "platform_liability_assumed_amount": 49.95,
                "seller_tax_number": "IE3764989CH",
                "tax_region": "EU",
                "tax_exempt": false,
                "additional_currencies": {
                    "consignment": {
                        "currency_code": "EUR",
                        "fx_date": "2021-09-22T11:49:18Z",
                        "fx_rate": 1,
                        "fx_source": "ECB"
                    }
                },
                "tax_country_code": "FR",
                "special_tax_scheme": "IOSS",
                "line_key": "dGuuCW0VHEx_etRF",
                "custom_id": "51315A00-DC44-408E-A575-8CE42A32AE1B",
                "tax_address_kind": "ship_to_address",
                "ship_from_address": {
                    "city": "London",
                    "country_code": "GB",
                    "postal_code": "SW1A 2AA",
                    "street_name": "Wessex End Street",
                    "building_number": "12",
                    "tax_region": "GB"
                },
                "tax_engine": "taxamo",
                "invoice_status": "R",
                "kind": "b2c",
                "tax_number_service": "vies",
                "product_class": "P",
                "tax_liability_owner_code": "Taxamo",
                "line_num": 1,
                "is_seller_permanent": true,
                "quantity": 1,
                "total_amount": 54.95,
                "seller_code": "seller_jftest_1",
                "product_cn_code": "0305420000",
                "tax_entity_name": "France",
                "tax_supported": true
            }
        ],
        "discounts": [],
        "location_evidence": {},
        "vouchers": [],
        "product_classes": "P",
        "billing_address": {
            "city": "Paris",
            "country_code": "FR",
            "postal_code": "75008 ",
            "street_name": "Rue du Saint-Germain",
            "address_detail": "Chateuax 12",
            "building_number": "55",
            "tax_region": "EU"
        },
        "buyer_name": "Eric Papin",
        "tax_timestamp": "2021-09-22T11:49:18Z",
        "total_amount": 54.95,
        "currency_code": "EUR"
    }
}