Transaction Fields
Each sale processed by Taxamo (physical or digital goods) 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
Request
| Field Name | Description |
|---|---|
| ship_to_address | The address of where the physical goods are being shipped to. |
| ship_from_country_code | The country code of the country where the goods are being shipped from. |
| description | Description of the goods being purchased. |
| 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) |
| parcel_reference | Unique reference number given on dispatch for items packaged together. |
| product_class | P for physical goods, D for digital goods. Physical and digital goods apply different logic and tax rates. |
| carrier_id | Unique identifier of the logistics company responsible for the delivery of goods. |
| consignment_id | Identifier of the package. Lines with the same package id are treated together for a single value in some regions when checking the IOSS threshold for example. |
| product_cn_code | Combined Nomenclature code for the product on this line. |
| import_scheme | if import scheme, such as IOSS has been used, it needs to be applied here. |
| 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: 2020-01-31. If this is not provided then the current date in Taxamo's timezone (GMT) will be used. |
| seller_code | A unique identifier of the Seller providing the goods. Depending on LILA logic, the sale might get assigned to this Seller, the Marketplace or the Buyer. |
| buyer_email | the buyer's email address. It can be used for invoice image delivery. |
Response (key additional fields)
| Field Name | Description |
|---|---|
| line_key | A unique transaction identifier in Taxamo. This is generated by Taxamo. |
| tax_liability_owner_codes | Identifies the party who is obliged to pay the tax (Marketplace, Seller or Buyer). |
| tax_liability_rule | The logic used to identify the tax liability owner. |
| tax_amount | The sum of taxes. This is calculated by Taxamo. |
| tax_country_codes | The country code of the tax authority of which the tax must be paid to. |
| tax_region | This relates to the scope of the tax regulations being applied, so it could be on a country level or it could be a tax region level. |
| taxes[] | List of taxes applied to the line |
| tax_rate | The rate of tax being applied to that particular line item. |
| reverse_charge | If true, this means that this line had a reverse charge applied. |
| invoice_number | number of the invoice that includes this line. Multiple lines can be assigned to a single invoice |
| invoice_image_url | URL of the invoice that includes this line. |
| invoice_image_url_secret | Secret part of the invoice image url - this is an additional protection against guessing the invoice image url from known transaction key and unknown invoice number. |
Location evidence fields (digital goods)
EU VAT rules state that two non-conflicting pieces of evidence must be collected during the customer journey to determine the correct VAT rate to apply at checkout.
The acceptable types of evidence to collect include:
- Commercially relevant information.
- Location of customer’s fixed landline through which the service is supplied.
- Bank details: location of the bank account used for payment or the billing address of the customer * held by that bank.
- The IP address of the device used by the customer.
- Billing address of the customer.
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:
| Field | Description |
|---|---|
| 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). |
| 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. |
Tax information fields
The tax information fields are set by Taxamo, and include:
Request
| Field | Description |
|---|---|
| custom_id | required for each line. The value needs to be unique transaction-wide. |
| amount, total_amount, unit_price | Either of these fields must be provided. Other values are calculated from the highest ranking field provided. |
| quantity | number of items in the transaction line. Defaults to 1. |
| *product_type | Some product types might have different tax rates in different regions. |
| description | Describes the goods being purchased. The description field will be shown on the standard invoice template. |
Response (key additional fields)
| Field | Description |
|---|---|
| line_key | Taxamo's line key identifier. Generated by Taxamo. |
| 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. |
Custom / descriptive fields
Marketplaces using the customs fields so they can referenced at a later stage - for example, in the invoice. It is a way for them to send in extra information that is relevant to their business.
Custom/descriptive field options include:
| Field | Description |
|---|---|
| custom_id | Custom identifier of a transaction at transaction level |
| 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:
| Field Name | Description |
|---|---|
| buyer_name | Buyer's name |
| invoice_address | Invoice address to be displayed on the invoice |
| invoice_number | Invoice number. There are rules around the invoice numbering - country specific - generally it needs to be a sequential number, prefixed with the country code, maybe the year. It can be configured that the Marketplace will supply the invoice_number in the request, or Taxamo can generate one if required. |
| invoice_image_url | Invoice HTML image url, generated by Taxamo. |
Credit notes
The Taxamo invoicing solution provides merchants with the ability to send compliant invoices to their customers for confirmed (completed) transactions, as well as issuing compliant credit notes for refunds.
Templates for Credit Notes can be configured on the dashboard and contain key data points such as:
- Description of Goods
- Original Amount
- Amount Credited
- Tax Credited
- Total Credited
- VAT # of Marketplace or Seller
- Customer name & address
Updated over 4 years ago