This documentation is for Taxamo v1. If your account is with Taxamo v2 use the documentation at integrate.taxamo.com/doc.
If you are uncertain of your version please contact support@taxamo.com for assistance.

How can I enact universal pricing via the Taxamo API?

There are two ways to enact universal pricing:

  1. Override the total_amount field when calling the API.
  2. Enabling the Force Universal setting in the dashboard.

The following explains the difference, using examples with a UK merchant and an Irish customer.

1. Override the total_amount field when calling the API

With the FORCE UNIVERSAL setting turned off in the dashboard, when you call the Taxamo API and populate the total_amount field our service determines the appropriate tax rate and calculates the tax_amount and amount fields.

Here are two examples, showing the different treatment for B2B and B2C transactions. Note particularly that even though the total_amount of 100 was supplied in both cases, the B2B case does not have a VAT charge so the tax was deducted from the total_amount, but the B2C case has the VAT added on top of the amount.

B2C (no VAT number)

CALL:

{
    "transaction": {
        "transaction_lines": [
            {
                "custom_id": "line1",
                "amount": 100
            }
        ],
        "currency_code": "EUR",
        "billing_country_code": "IE"
    }
}

RESULT:

{ 
	"transaction_lines": [
    {
    	"line_key": "Waxq-IgyvhItLT6o",
       	"custom_id": "line1",
       	"quantity": 1,
       	"product_type": "default",
       	"total_amount": 100,
       	"amount": 81.3,
       	"tax_amount": 18.7,
       	"line_num": 1,
       	"tax_name": "European VAT",
       	"tax_rate": 23,
       	"unit_price": 81.3
    }
}

B2B (VAT number supplied)

CALL:

{
    "transaction": {
        "transaction_lines": [
            {
                "custom_id": "line1",
                "amount": 100
            }
        ],
        "currency_code": "EUR",
        "buyer_tax_number": "IE3184089FH",
        "billing_country_code": "IE"
    }
}

RESULT:

{
	"transaction_lines": [
    {
       "line_key": "4rYFAeXP_p4fSVpr",
       "custom_id": "line1",
       "quantity": 1,
       "product_type": "default",
       "total_amount": 100,
       "amount": 100,
       "tax_amount": 0,
       "line_num": 1,
       "tax_name": "European VAT",
       "tax_rate": 0,
       "unit_price": 100
    }
}

2. Enabling the Force Universal setting in the dashboard

Alternatively, if the FORCE UNIVERSAL setting is enabled in the dashboard then Taxamo assumes the amount field contains the universal price.

As shown below, both transactions returned the same total_amount of 100 as expected, but the B2C had VAT charged and the B2B did not.

B2C (no VAT number)

CALL:

{
    "transaction": {
        "transaction_lines": [
            {
                "custom_id": "line1",
                "amount": 100
            }
        ],
        "currency_code": "EUR",
        "billing_country_code": "IE"
    }
}

RESULT:

{
    "transaction_lines": [
    {
        "tax_amount": 18.7,
        "tax_name": "European VAT",
        "unit_price": 81.3,
        "tax_rate": 23,
        "quantity": 1,
        "total_amount": 100,
        "custom_id": "line1",
        "amount": 81.3
    }
}

B2B (VAT number supplied)

CALL:

{
    "transaction": {
        "transaction_lines": [
            {
                "custom_id": "line1",
                "amount": 100
            }
        ],
        "currency_code": "EUR",
        "buyer_tax_number": "IE3184089FH",
        "billing_country_code": "IE"
    }
}

RESULT:

{
    "transaction_lines": [
    {
        "tax_amount": 0,
        "tax_name": "European VAT",
        "total_amount": 100,
        "unit_price": 100,
        "tax_rate": 0,
        "quantity": 1,
        "custom_id": "line1",
        "amount": 100
     }
}

Comparison of examples without Universal Pricing

For purposes of comparison, here are B2B and B2C examples without Universal Pricing.

In each case the amount is supplied and the tax is determined dynamically, the difference being that the B2B does not have tax so the amount and total_amount result fields are the same.

B2C (no VAT number)

CALL:

{
    "transaction": {
        "transaction_lines": [
            {
                "custom_id": "line1",
                "amount": 100
            }
        ],
        "currency_code": "EUR",
        "billing_country_code": "IE"
    }
}

RESULT:

{
  "transaction_lines": [
    {
        "tax_amount": 23,
        "tax_name": "European VAT",
        "unit_price": 100,
        "tax_rate": 23,
        "quantity": 1,
        "total_amount": 123,
        "custom_id": "line1",
        "amount": 100
    }
}

B2C (VAT number supplied)

CALL:

{
    "transaction": {
        "transaction_lines": [
            {
                "custom_id": "line1",
                "amount": 100
            }
        ],
        "currency_code": "EUR",
        "buyer_tax_number": "IE3184089FH",
        "billing_country_code": "IE"
    }
}

RESULT:

{
   "transaction_lines": [
    {
        "tax_amount": 0,
        "tax_name": "European VAT",
        "unit_price": 100,
        "tax_rate": 0,
        "quantity": 1,
        "total_amount": 100,
        "custom_id": "line1",
        "amount": 100
     }
}

Note: In B2B cases where the merchant and the customer are based in the same country this is referred to as a domestic B2B transaction and tax must be collected, and even this can be overridden with the setting “do NOT charge tax on domestic transactions”.