Important Fields

Read about some of the more significant fields that you can use when you model your requests or that may contain information that is returned by the API.

Main Fields

The main fields describe the transaction in general and are used in the majority of cases. These fields include the following:

Field

Description

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 this is set to true, the transaction has been created using the TEST mode token.

key

A unique transaction identifier that is generated by the service.

amount

The base amount, not including taxes.

total_amount

The total amount, including taxes.

tax_amount

The sum of taxes. This is generated by the service.

sub_account_id

If this is set, this transaction has the VAT/GST obligation taken over by Vertex.

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 the following fields:

Field

Description

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 (for example 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 (for example 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 (for example GB).

Tax Information Fields

Tax information is returned in responses sent from the API in the following fields:

Field

Description

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 as derived by the service.

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 validated. 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:

Field

Description

custom_id

This is required for each line. The value needs to be unique transaction-wide.

line_key`

Line key identifier generated by the service.

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

The tax amount that is applied.

tax_rate

The tax rate (in percents) applied to this transaction line. Provided by Taxamo.

tax_name

The name of the tax, generated by the service.

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:

Field

Description

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:

Field

Description

buyer_name

Buyer's name.

invoice_address

invoice address to be displayed on the invoice.

invoice_number

The invoice number, that is generated by the service.

invoice_image_url

The invoice HTML image URL, that is generated by the service.


Did this page help you?