GuidesAPI ReferenceAnnouncements

Transaction Fields

Suggest Edits

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.

Main fields

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: EUR, USD, CNY.
  • order_date - the sale date, in the yyyy-MM-dd format. Example: 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 true the 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.

Location evidence fields

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).

Tax information fields

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_number has been checked OK. If set to false, the number has been checked but it has been deemed invalid. 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.

Transaction lines

All of the sale elements need to be provided as transaction lines. The most commonly used fields on each item in transaction_lines[] are:

  • custom_id - required for each line. The value needs to be unique transaction-wide.
  • line_key - Taxamo's line key identifier. Generated by Taxamo.
  • amount, total_amount, unit_price - amount fields, either amount, unit_price or total_amount has to be provided. Other values are calculated from the highest ranking field provided.
  • quantity - number of items in the transaction line. Defaults to 1.
  • 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 fields

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 key and value attributes. Can be set on either the transaction or transaction line level.

Invoice information

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.

Updated over 3 years ago