Calculate tax

This requests calculates the tax based on the priovided information. However, the data is not stored. This request is often used to provide a quote or calculate prices quickly on a product page.

To calculate tax, use a POST method and the following URL:

https://{service_url}/api/v2/tax/calculate

where {service_url} is the URL of the service's environment.

Details

Type	Value
Endpoint	`/api/v2/tax/calculate`
Method	POST
API Reference	Calculate tax

Body Parameters

Parameter	Description
`private_token`	Private token.
`force_storage_fields_check`	If true, will check if storage fields are present for non-delegated transactions as well.
`transaction`	See Transaction Schema.

Request Example

The following is an example request:

{
  "transaction": {
    "currency_code": "EUR",
    "transaction_lines": [
      {
        "custom_id": "line1",
        "amount": 100
      }
    ],
    "billing_country_code": "BE",
    "buyer_credit_card_prefix": "424242424"
  },
  "private_token": "private_***********"
}

Response Examples

The following example shows a successful response the tax is supported (tax_supported=true):

{
    "is_delegated": true,
    "transaction": {
        "amount": 100.0,
        "custom_fields": [],
        "kind": "eu-b2c",
        "tax_supported": true,
        "tax_country_codes": "FR",
        "tax_amount": 20.0,
        "tax_deducted": false,
        "tax_region": "EU",
        "billing_country_code": "FR",
        "evidence": {
            "by_ip": {
                "evidence_value": "x.x.x.x",
                "used": true,
                "resolved_country_code": "FR",
                "evidence_type": "by-ip"
            },
            "by_billing": {
                "evidence_value": "FR",
                "used": true,
                "resolved_country_code": "FR",
                "evidence_type": "by-billing"
            }
        },
        "additional_currencies": {
            "invoice": {
                "currency_code": "EUR",
                "fx_rate": 0.910580950647,
                "amount": 91.06,
                "tax_amount": 18.21,
                "total_amount": 109.27
            }
        },
        "tax_country_code": "FR",
        "countries": {
            "by_ip": {
                "code": "FR",
                "tax_supported": true,
                ...
            },
            "by_billing": {
                "code": "FR",
                "tax_supported": true,
                ...
            },
            "detected": {
                "code": "FR",
                "tax_supported": true,
                ...
            }
        },
        "transaction_lines": [
            {
                "amount": 100.0,
                "unit_price": 100.0,
                "tax_amount": 20.0,
                "tax_deducted": false,
                "tax_region": "EU",
                "tax_rate": 20,
                "additional_currencies": {},
                "tax_country_code": "FR",
                "line_key": "hKeqLHqdhk7LTayq",
                "custom_id": "1",
                "tax_name": "European VAT",
                "tax_number_service": "vies",
                "line_num": 1,
                "deducted_tax_amount": 0.0,
                "quantity": 1.0,
                "total_amount": 120.0,
                "deducted_tax_rate": 0,
                "tax_entity_name": "France",
                "tax_supported": true
            }
        ],
        "buyer_ip": "x.x.x.x",
        "refunded_tax_amount": 0,
        "force_country_code": null,
        "country_name": "France",
        "product_classes": "D",
        "fully_informative": false,
        "tax_engine": "taxamo",
        "tax_number_service": "vies",
        "refunded_total_amount": 0,
        "order_date_type": "timestamp",
        "shipment_country_data": {},
        "deducted_tax_amount": 0.0,
        "order_date": "2019-09-26T10:12:02Z",
        "total_amount": 120.0,
        "tax_timezone": "Europe/Dublin",
        "sub_account_id": "xxxxx",
        "tax_entity_name": "France",
        "currency_code": "USD"
    },
    "tax_required_fields": [],
    "storage_required_fields": []
}

The following example shows a successful response the tax is not supported (tax_supported=false):

{
    "is_delegated": false,
    "transaction": {
        "amount": 100.0,
        "custom_fields": [],
        "tax_supported": false,
        "tax_country_codes": "BR",
        "tax_amount": 0,
        "tax_deducted": false,
        "billing_country_code": "BR",
        "evidence": {
            "by_payment_method": {
                "evidence_value": "BR",
                "resolved_country_code": "BR",
                "used": true,
                "evidence_type": "by-payment-method"
            },
            "by_billing": {
                "evidence_value": "BR",
                "used": true,
                "resolved_country_code": "BR",
                "evidence_type": "by-billing"
            }
        },
        "tax_country_code": "BR",
        "countries": {
            "by_billing": {
                "code": "BR",
                "tax_supported": false,
                ...
            },
            "by_payment_method": {
                "code": "BR",
                "tax_supported": false,
                ...
            },
            "detected": {
                "code": "BR",
                "tax_supported": false,
                ...
            }
        },
        "transaction_lines": [
            {
                "amount": 100.0,
                "unit_price": 100,
                "tax_deducted": false,
                "tax_country_code": "BR",
                "line_key": "rP0gJrIqodGcuwVR",
                "custom_id": "1",
                "line_num": 1,
                "deducted_tax_amount": 0,
                "quantity": 1,
                "total_amount": 100.0,
                "deducted_tax_rate": 0,
                "tax_supported": false
            }
        ],
        "refunded_tax_amount": 0,
        "force_country_code": null,
        "country_name": "Brazil",
        "product_classes": "D",
        "fully_informative": false,
        "refunded_total_amount": 0,
        "order_date_type": "timestamp",
        "shipment_country_data": {},
        "deducted_tax_amount": 0,
        "order_date": "2019-09-26T09:19:02Z",
        "total_amount": 100.0,
        "tax_timezone": "GMT",
        "sub_account_id": "xxxxx",
        "currency_code": "USD"
    },
    "tax_required_fields": [],
    "storage_required_fields": []
}

Example Error Responses

The following is an example of a 400 error code response (missing_tax_required_fields, missing_storage_required_fields):

{
    "errors": [
        "Please provide invoice_address.region."
    ],
    "error_code": "missing_tax_required_fields",
    "tax_supported": true,
    "tax_country_code": "CA",
    "tax_region": "CA",
    "tax_required_fields": [
        {
            "field_name": "invoice_address.region"
        }
    ],
    "storage_required_fields": [
        {
            "field_name": "invoice_address.city"
        },
        {
            "field_name": "invoice_address.postal_code"
        }
    ],
    "evidence": {
        "by_payment_method": {
            "evidence_value": "CA",
            "resolved_country_code": "CA",
            "used": true,
            "evidence_type": "by-payment-method"
        },
        "by_billing": {
            "evidence_value": "CA",
            "used": true,
            "resolved_country_code": "CA",
            "evidence_type": "by-billing"
        }
    },
    "countries": {
        "by_payment_method": {
            "code": "CA",
            "tax_supported": true,
            ...
        },
        "by_billing": {
            "code": "CA",
            "tax_supported": true,
            ...
        },
        "detected": {
            "code": "CA",
            "tax_supported": true,
            ...
        }
    },
    "product_classes": "D",
    "currency_code": "USD"
}

The following is an example of a 400 error response (error_code = validation_error):

{
    "errors": [
        "Unknown currency."
    ],
    "error_code": "validation_error"
}