Each sale processed by Taxamo is represented by a transaction. This section provides a general overview of the relevant transaction fields.
For more detailed information, please consult our API documentation.
The main fields describe the transaction in general and are used in the majority of cases. These fields include:
currency_code- required for each transaction, a 3-letter ISO code for the currency used. Examples:
order_date- the sale date, in the
2016-12-31. If this is not provided then the current date in Taxamo's timezone (GMT), for delegated transactions, or the merchant's timezone for non-delegated transactions will be used.
buyer_email- the buyer's email address. It can be used for invoice image delivery.
test- if set to
truethe transaction has been created using the TEST mode token.
key- a unique transaction identifier in Taxamo. This is generated by Taxamo.
amount- the base amount, not including taxes (tax amount is calculated by Taxamo).
total_amount- the total amount, including taxes (tax amount is calculated by Taxamo).
tax_amount- the sum of taxes. This is calculated by Taxamo.
sub_account_id- if set this transaction has the VAT/GST obligation taken over by Taxamo.
For each evidence kind, the
evidence_value field should be provided. If the evidence resolves correctly Taxamo
will return updated information for each piece of evidence. This information will contain:
evidence[by_tax_number].evidence_value- if provided, and the transaction resolves to a supported country, it will be checked with an online system provided by the region's tax authority, marking it as B2B upon successful validation. In some regions B2B transactions assume the reverse charge mechanism, where the buyer has to settle the VAT/GST obligation themselves.
evidence[by_ip].evidence_value- the customer's IP address used to make the purchase.
evidence[by_cc].evidence_value- the customer's credit card BIN (Bank Identification Number).
evidence[by_billing].evidence_value- the customer's billing country, a 2-letter ISO code.
evidence[by_payment_method].evidence_value- if the payment method has provided country evidence, please specify the 2-letter ISO country code here (e.g. GB)
evidence[by_self_declaration].evidence_value- if the customer has provided a self-declared country code, please specify the 2-letter ISO country code here (e.g. GB)
evidence[ other_commercially_relevant_info].evidence_value- if the payment method has provided country evidence, please specify the 2-letter ISO country code here (e.g. GB).
The tax information fields are set by Taxamo, and include:
tax_deducted- if set to true, the transaction will have no tax applied even though it is created in a taxable region.
tax_country_code- resolved tax country code, calculated by Taxamo.
tax_supported- set to true if tax calculation is supported in the location detected.
kind- transaction kind, provided by Taxamo.
buyer_tax_number_valid- if set to
true, the provided
buyer_tax_numberhas been checked OK. If set to
false, the number is correct. If present and set to
null- the check has failed - for example the Tax Authority's system was offline. If not present, the tax number wasn't checked.
All of the sale elements need to be provided as transaction lines. The most commonly used fields on each item in
custom_id- required for each line. The value needs to be unique transaction-wide.
line_key- Taxamo's line key identifier. Generated by Taxamo.
unit_price- amount fields, either
total_amounthas to be provided. Other values are calculated from the highest ranking field provided.
quantity- number of items in the transaction line. Defaults to
tax_amount- tax amount applied.
tax_rate- tax rate (in percents) applied to this transaction line. Provided by Taxamo.
tax_name- tax name - if present. Provided by Taxamo.
product_type- defaults to
default. Some product types might have different tax rates in different regions.
description- the description field will be shown on the standard invoice template.
Custom/descriptive field options include:
custom_id- custom identifier of a transaction.
customer_id- customer's id.
description- transaction/transaction line description.
custom_fields- an array of objects with
valueattributes. Can be set on either the transaction or transaction line level.
Fields used to populate invoice information include:
buyer_name- buyer's name.
invoice_address- invoice address to be displayed on the invoice.
invoice_number- invoice number, generated by Taxamo.
invoice_image_url- invoice HTML image url, generated by Taxamo.