Tax identifiers
Learn how to manage and apply tax identifiers.
In versions
2021-02-23 and later, use the features described on this page to manage tax identifiers. Once you upgrade to any of these versions, the tax identifiers you previously created through the Customers API will no longer be available. Please contact us to have your data migrated.For versions
2020-12-17 and earlier, refer to the Tax identifiers (legacy) section on the Setting up tax exemptions page.When you create a tax identifier, we initiate a validation process. Once the tax identifier object transitions to the appropriate verification state, and assuming it's applicable to the order, it can be used to determine an order's taxability.
To apply a tax identifier, you can attach it directly to a checkout or invoice. Alternatively, you can associate it with a customer and then use it in registered checkouts.
Your checkout flow should also take into account that some countries require tax identifiers. When a customer in one of these countries doesn't supply a tax identifier, we block the order and provide notification of the problem.
In most value-added tax (VAT) schemes, domestic sales to business customers are assessed tax and customers then take a credit for this tax paid when they complete their monthly or quarterly VAT return. In these cases, customers need the invoice to display their tax identifier so they can obtain this credit.
Alternatively, cross-border sales to business customers are not assessed tax in most VAT schemes. Instead, in a practice called reverse charge, customers self-assess the tax while simultaneously taking a credit for the tax when they complete their monthly or quarterly VAT return. In these cases, the tax identifier is used to determine whether or not reverse charge applies to a specific order.
Additionally, in a limited number of cases, tax identifiers are collected because they are required by a specific country’s tax authority for invoicing purposes.
In the Digital River APIs, a tax identifier is always represented by a unique identifier. Additionally, the object will contain attributes that indicate its type and value, its state, and created time.
In some cases, a tax identifier may also include a customer identifier, a verified name and address, and an updated time.
JSON
{
"id": "a6809a63-e6a9-4016-abbc-f33d19fccb5b",
"createdTime": "2018-04-25T20:36:00Z",
"updatedTime": "2018-04-28T22:16:00Z",
"customerId": "5774321009",
"type": "de",
"value": "DE123456789",
"state": "verified",
"stateTransitions": {
"verified": "2020-05-30T06:52:31.041Z",
"pending": "2020-05-30T06:45:12.041Z"
}
}
A tax identifier is always returned with a unique
id. Besides using this identifier to retrieve and delete a tax identifier, you can use it to attach a tax identifier to a checkout or associate it with a customer.The
type attribute identifies the country that issued the tax identifier. The available types typically consist of a lowercase, two-letter country code. However, there are some countries that have more than one type and these contain a suffix to the country code. For example, Brazil has tax identifiers with types of br, br_ie, and br_natural.The
value is assigned by the issuing country. Before creating a tax identifier, you can use the tax identifier element to help you validate its format. This element also lets you know whether a tax identifier is required in the country where the purchase is being made.A tax identifier can be in a state of
pending, not_valid, and verified. Its state is dependent on where it is in the verification process.Each state transition causes a corresponding event to be emitted whose
data.object consists of the tax identifier.(1) When the tax identifier is... | (2) its state transitions to... | (3) and a...event is emitted. |
|---|---|---|
under review by an external verification agency | pending | tax_identifier.pending |
determined to be valid | verified | tax_identifier.verified |
determined to be invalid | not_valid | tax_identifier.not_valid |
A tax identifier in any state can be attached directly to a checkout or associated with a customer. Before taking either action, your integration should ideally wait to receive the
tax_identifier.verified event. However, a tax identifier in either a pending or verified state is used to determine an order's taxability.Additionally, as it moves from one state to another, an ISO8601 formatted date and time is returned in the
stateTransitions hash table.During the tax identifier verification process, we sometimes are able to obtain the holder's
verifiedName and verifiedAddress.A tax identifier always contains a
createdTime. When a tax identifier is associated with a customer, its state changes, or the holder's name and address is added, then the time these events occurred is reflected in the updatedTime field.When a
POST/ tax-identifiers request is submitted, Digital River initiates a validation process. As part of this process, we always validate the format of a tax identifier, whatever its country of origin. Incorrectly formatted tax identifiers return the following error:400 Bad Request
{
"type": "bad_request",
"errors": [
{
"code": "invalid_parameter",
"parameter": "value",
"message": "Tax identifier 'IT00121239990xxxx' invalid."
}
]
}
For European Union tax identifiers, commonly known as Value Added Tax (VAT) numbers, we use the VAT Information Exchange System (VIES) to validate customer's data.
After a
POST /tax-identifiers is submitted, Digital River provides VIES the data submitted in the request. VIES, in turn, transmits our validation query to the database of the relevant member state. The member state's reply to VIES indicates whether the number exists and, if so, whether it's valid. The reply may also include the holder's name and address. VIES then relays this information back to us.VIES no longer verifies VAT numbers from Great Britain.
If VIES successfully responds before the checkout is converted to an order, then the tax identifier's
state transitions to either verified or not_valid . This causes either a tax_identifier.verified or tax_identifier.not_valid event to fire. If the number is verified, then the tax identifier is immediately applied to the order.In many situations, however, VIES responds slowly or is down for scheduled or unscheduled reasons. This means the tax identifier might not transition from
pending to verified until after order creation. In these cases, we treat a pending tax identifier as being verified until we know otherwise. In other words, pending and verified tax identifiers are both used by Digital River to determine an order's taxability.If VIES indicates a tax identifier is
not_valid, then we don't use it to determine an order's taxability. For certain countries, we also apply validation algorithms defined by the local authority that issued the number.
Before a tax identifier can be successfully applied to a checkout, the tax identifier type, the customer type, the selling entity, and the country (a ship to country for physical goods or a bill to country for digital goods) must all be in agreement.
With a few notable exceptions, most countries only allow
business customers to apply tax identifiers.For example, the following is a partial response to a
POST/orders request. In this case, a tax identifier has been successfully applied. This is because the tax identifier's type is in agreement with the order's shipTo.country and the customer is a business entity.201 Created
{
"id": "9182309218",
...
"customerId": "5774321009",
...
"shipTo": {
"address": {
...
"country": "GB"
},
...
},
"customerType": "business",
...
"taxIdentifiers": [{
"id": "a6809a63-e6a9-4016-abbc-f33d19fccb5b",
"customerId": "5774321009",
"type": "uk",
"value": "GB123283536",
"state": "verified",
"stateTransitions": {
"pending": "2020-05-13T11:00:00.000Z",
"verified": "2020-05-15T16:00:00.000Z"
},
"verified_name": "A.C. Doyle Inc.",
"verified_address": "Hudson House, 221B Baker Street, London",
"createdTime": "2020-08-01T02:25:53Z",
"updatedTime": "2020-08-01T05:47:21Z"
}],
...
}
If you were to submit another
POST/orders request with the same settings—the only difference being that in the new request you specified ashipTo.country of DK (Denmark)—you'd receive a 409 Conflict response. This is because customers holding tax identifiers issued by one country can't apply them to orders being shipped to a different country.409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "invalid_parameter",
"parameter": "taxIdentifiers",
"message": "Tax identifiers of type 'uk' are not applicable to this order."
}
]
}
Digital River first searches for applicable tax identifiers that are directly attached to a checkout or invoice. This is true whether you're checking out a guest customer or a registered customer.
However, when it's a registered checkout and that customer has associated tax identifiers that are applicable, and those tax identifiers are not yet attached, we apply them as well.
If no tax identifiers are directly attached to a checkout or invoice, and it's a guest customer making the purchase, we don't use any tax identifiers when computing taxes.
Before they are applied to orders, we provide you the ability to validate the tax identifier information provided by customers. Once validated, you can use the Tax Identifiers API to create, retrieve, delete, and search for them.
You can also attach tax identifiers to customers and then later, if necessary, detach them. To reassign or replace tax identifiers, you must first delete the existing object before creating a new one.
To validate the format entered by a customer and determine whether a tax identifier is both required and applicable to the transaction, you can use the tax identifier element. To create the element, you must use some combination of the selling entity identifier, payment session identifier, and ship to/bill to ISO 3166 country code returned in a Checkout or Invoice.
When you configure the element with a payment session identifier, we filter out tax identifiers that are not applicable to the transaction.
You use the
POST/tax-identifiers method to create a tax identifier. In the request, you must specify both a type and value. Once the request is submitted, we initiate a validation process.POST/tax-identifiers
curl --location --request POST 'https://api.digitalriver.com/tax-identifiers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
"type": "de",
"value": "DE123456789"
}'
The following is an example
201 Created response. It doesn't contain a customerId because the tax identifier hasn't been attached to a customer yet. The pending state of the tax identifier indicates it's still being validated by an external agency.201 Created
{
"id": "a6809a63-e6a9-4016-abbc-f33d19fccb5b",
"createdTime": "2018-04-25T20:36:00Z",
"updatedTime": "2018-04-28T22:16:00Z",
"type": "de",
"value": "DE123456789",
"state": "pending",
"stateTransitions": {
"pending": "2020-05-30T06:45:12.041Z"
}
}
You can delete a tax identifier by submitting a
DELETE/tax-identifiers/{id} request that sends its unique identifier as a path parameter. A successful request returns a 204 No Content response. It also triggers a tax_identifier.deleted event and detaches the tax identifier from any customer it may have been associated with.Once a tax identifier is deleted, if you later attempt to attach it to a customer, you'll get the following
404 Not Found error.404 Not Found
{
"type": "not_found",
"errors": [
{
"code": "not_found",
"parameter": "id",
"message": "Tax identifier '88b8fd94-14bd-4711-b381-9f73abef1546' not found."
}
]
}
Once you've created a tax identifier, you can use the
POST/customers/{id}/tax-identifiers/{taxId} method to attach it to an existing customer. This request returns the tax identifier and triggers a customer.tax_identifier.created event. The data.object of the event also represents the tax identifier.Since it's now associated with a customer, the
customerId attribute is populated in the response. The following example response shows a British (uk) issued tax identifier in a verified state. When the customer next makes an applicable purchase, this tax identifier will be automatically applied to the order.200 OK
{
"id": "a6809a63-e6a9-4016-abbc-f33d19fccb5b",
"customerId": "5774321009",
"type": "uk",
"value": "GB123283536",
"state": "verified",
"stateTransitions": {
"pending": "2020-05-13T11:00:00.000Z",
"verified": "2020-05-15T16:00:00.000Z"
},
"verified_name": "Royal Flushing Inc.",
"verified_address": "Westminster, London SW1A 1AA, United Kingdom",
"createdTime": "2020-08-01T02:25:53Z",
"updatedTime": "2020-08-01T05:47:21Z"
}
To disassociate a tax identifier from a customer, send a delete request through the Tax Identifiers API. A successful request means that when the customer creates applicable registered checkouts in the future, this tax identifier will no longer be applied.
The same tax identifier object can't be attached to multiple customers. If you attempt to associate a tax identifier with a customer, but it's already attached to a different customer, you'll receive a
409 Conflict response.409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "customer_not_updateable",
"parameter": "customerId",
"message": "You cannot replace a tax identifier's customer id."
}
]
}
In these cases, you must first delete the tax identifier, create a new object with an identical type and value, and then assign it to the desired customer.
Customers can have multiple tax identifiers, but they can't have more than one of the same type. So if you'd like to attach a new tax identifier to a customer, but that customer already holds one with that
type, you must first delete the existing object. Once you've consumed either the 204 No Content response or the tax_identifier.deleted event, your integration can then create the new tax identifier and attach it to the same customer.Once they are created, there are two ways to apply tax identifiers to a purchase. You can either attach the tax identifier directly to a checkout or invoice. Or you can use tax identifiers in registered checkouts.
In either case, during the checkout process, we determine whether the tax identifier is applicable and notify you of missing tax identifiers.
You should also ensure you pass the necessary information to correctly display the tax identifier on invoices.
When checking out both registered and guest customers, you can attach tax identifiers directly to a checkout or invoice. You do this by using a
POST/checkouts,POST/checkouts/{id}, or POST/invoices request and sending the object's identifier in the taxIdentifiers array.POST/checkouts
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
"customerId": 520984250336,
...
"taxIdentifiers": [{
"id": "2bba2529-97cb-4f0e-872f-5d97ac242cc0"
}],
...
}'
A successful response returns a checkout or invoice that contains an array of tax identifier objects. The
state of each tax identifier, which indicates whether it will be used to determine an order's taxability, depends on how it is validated.201 Created
{
"id": "1003189166920",
....
"customerId": "520984250336",
...
"shipTo": {
"address": {
"line1": "Neuschwansteinstraße 20",
"city": "Schwangau",
"postalCode": "87645",
"country": "DE"
},
"organization": "Wagner,LLC",
...
},
...
"customerType": "business",
...
"sellingEntity": {
"id": "DR_IRELAND-ENTITY",
"name": "Digital River Ireland Ltd."
},
"taxIdentifiers": [
{
"id": "2bba2529-97cb-4f0e-872f-5d97ac242cc0",
"customerId": "520984250336",
"type": "de",
"value": "DE231287923",
"state": "verified",
"stateTransitions": {
"pending": "2020-12-23T16:00:00.000Z",
"verified": "2020-12-23T16:00:00.000Z"
},
"verifiedName": "Checkpoint Security Services Ltd.",
"verifiedAddress": "Friedrichstraße 43-45, 10117 Berlin, Germany",
"createdTime": "2020-12-23T15:21:26Z",
"updatedTime": "2020-12-23T15:21:26Z"
}
],
...
}
For registered checkouts, any tax identifiers directly attached to the checkout must be associated with the customer placing the order. If any are held by a different customer, the following
409 Conflict response is returned:409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "tax_identifier_in_use",
"parameter": "taxIdentifiers",
"message": "Tax identifier 'a6809a63-e6a9-4016-abbc-f33d19fccb5b' is attached to a different customer."
}
]
}
When using a customer's saved tax identifier, make sure you determine whether it exists. If you associate a tax identifier with a checkout, but the object has been deleted, we return the following error:
409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "not_found",
"parameter": "id",
"message": "Tax identifier 'a6809a63-e6a9-5029-abbc-f66d19fccbcb' not found."
}
]
}
This information in this section is only applicable to versions
2021-03-23 and earlier of the Digital River APIs.For more information, refer to registered checkouts on the Checking out guest and registered customers page.
When you create a registered checkout, we search for applicable tax identifiers attached to that customer. If we locate any, they are automatically applied to the checkout or invoice and returned in its
taxIdentifiers array.You can send an empty
taxIdentifiers array to instruct Digital River not to automatically apply tax identifiers.For example, let's say a business customer holds a tax identifier of type
dk (Denmark) and another of type uk (Great Britain). In a POST/checkouts request, you associate this customer with the checkout and specify a ship to country of GB(Great Britain).In this case, only the
uk tax identifier is returned in the response. This is because tax identifiers are not applied to purchases when the type and ship to country are not in agreement.201 Created
{
"id": "9182309218",
...
"customerId": "5774321009",
...
"shipTo": {
"address": {
...
"country": "GB"
},
...
},
"customerType": "business",
...
"taxIdentifiers": [{
"id": "a6809a63-e6a9-4016-abbc-f33d19fccb5b",
"customerId": "5774321009",
"type": "uk",
"value": "GB000283536",
"state": "verified",
...
}],
...
}
If you attach a tax identifier to a checkout and the necessary requirements are not met, you receive an error:
409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "invalid_parameter",
"parameter": "taxIdentifiers",
"message": "Tax identifier '0c38e49d-79d1-44a0-b484-472ca3f20cf3' is not applicable."
}
]
}
To avoid this, you can apply a filter using the tax identifier's
applicability block. This data structure contains the following attributes:Each attribute provides the required transaction values that must exist before a tax identifier can be successfully applied. In other words, the corresponding values in the checkout/invoice must be the same. If they're not, the tax identifier isn't applicable.
The
applicability block is especially useful with saved tax identifiers. But, if for some reason you decide not to use the tax identifier element as a filter, you can also use applicability with new tax identifiers.During registered checkouts, you can use
applicability to filter customers' saved tax identifiers and display this filtered list to them on your site. Once the transaction's customer type is set and we've assigned a selling entity, make a GET/customers/{id} request to retrieve the customer's saved tax identifiers.In registered checkouts, you can send an empty
taxIdentifiers array to instruct Digital River not to automatically apply tax identifiers.In the following example, a customer has two saved tax identifiers. Both are applicable for
DR_IRELAND-ENTITY facilitated transactions. The first tax identifier, however, is only appropriate for purchases made by individuals in Italy, while the other can be used for business transactions in the Netherlands.Next, use the checkout's
shipTo.country (or billTo.country for digital goods), sellingEntity.id, and customerType, along with the corresponding values in each of the customer's applicability blocks, to filter out the non-applicable tax identifiers.Customer
Checkout
{
"id": "541337030336",
...
"taxIdentifiers": [
{
"id": "a19d26e7-8b7d-40e8-8358-b0a8b7203796",
"state": "verified",
"customerId": "541337030336",
"type": "it_natural",
"value": "IT5555555555",
...
"applicability": [
{
"country": "IT",
"entity": "DR_IRELAND-ENTITY",
"customerType": "individual"
}
]
},
{
"id": "6f5d4cb6-3c66-4a0b-a2aa-31cc25d3016d",
"state": "verified",
"customerId": "541337030336",
"type": "nl",
"value": "NL555555555555",
...
"applicability": [
{
"country": "NL",
"entity": "DR_IRELAND-ENTITY",
"customerType": "business"
}
]
}
],
...
"type": "individual"
}
{
"id": "5d0f0213-d8ab-4cc7-b721-1df1567df758",
...
"customerId": "541337030336",
...
"shipTo": {
"address": {
"line1": "Via del Governo Vecchio 87",
"city": "Roma",
"postalCode": "00186",
"country": "IT"
},
...
},
"shipFrom": {
"address": {
"country": "GB"
}
},
...
"customerType": "individual",
"sellingEntity": {
"id": "DR_IRELAND-ENTITY",
"name": "Digital River Ireland Ltd."
},
...
}
After that, display this filtered list to the customer. Once the customer selects an option, attach that tax identifier to the transaction.
If a registered or guest customer supplies new tax identifier information during the checkout process, send the necessary data in a
POST/tax-identifiers request. You can then use applicability in the response to determine whether the checkout contains the matching country, selling entity, and customer type values.If it does, attach the tax identifier to the checkout. If not, inform the customer that they provided an ineligible tax identifier. In the following guest checkout, the customer supplied tax identifier is not applicable because the
customerType values are not in agreement.Tax Identifier
Checkout
{
"id": "a56be3b9-bdc1-4188-8ee9-b20b12264e48",
"state": "verified",
...
"type": "nl",
"value": "NL555555555555",
...
"applicability": [
{
"country": "NL",
"entity": "DR_IRELAND-ENTITY",
"customerType": "business"
}
]
}
{
"id": "e4fca0fa-b303-4840-a912-e116abe746ca",
...
"shipTo": {
"address": {
"line1": "Paulus Potterstraat 7",
"city": "Amsterdam",
"postalCode": "1071 DJ",
"country": "NL"
},
...
},
"shipFrom": {
"address": {
"country": "GB"
}
},
...
"customerType": "individual",
"sellingEntity": {
"id": "DR_IRELAND-ENTITY",
"name": "Digital River Ireland Ltd."
},
...
}
When you want to inform us that no tax identifiers should be applied to a registered checkout, submit a create or update request with an empty
taxIdentifiers array. This indicates that none of the customer's applicable tax identifiers should be used to determine the order's taxability.For example, if a customer selects a saved tax identifier during the checkout process, but later deselects it, you can submit the following
POST/checkouts/{id} request to ensure it's not applied.POST/checkouts/{id}
curl --location --request POST 'https://api.digitalriver.com/checkouts/183731720336' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
"customerId": 520984250336,
...
"taxIdentifiers": [],
...
}'
On the other hand, not including the
taxIdentifiers array in a registered checkout has no affect. In this scenario, we automatically apply any applicable tax identifiers that are saved to the customer's account.For some countries, customers are required to provide a valid tax identifier when conducting online transactions. If customers in these countries don't provide this information, Digital River blocks their order from being placed.
During the checkout process, you can use the tax identifier element to determine whether a tax identifier is required in the customer's country.
As an example, let's say a
POST/checkouts request specifies a customer type of individual and a ship-to country of BR (Brazil). In that same request, if no tax identifiers with a type of br_natural are either attached directly to the checkout or associated with the customer placing the order, you'll receive a 409 Conflict response.409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "additional_information_required",
"parameter": "taxIdentifiers",
"message": "Tax identifiers of type 'br_natural' are required with this selling entity."
}
]
}
After an order is successfully fulfilled, and you've received the necessary events, you can share the generated invoice with customers. When its a business customer applying a tax identifier, the company name needs to be displayed on these invoices. To ensure this happens, you must set the
organization parameter when specifying a shipping address for orders that contain physical products.The following table lists the combination of ship to country, tax id type, customer type, and selling entity that must be in alignment before a tax identifier can be applied to an order.
As the table indicates, most countries don't require a tax identifier when making an online purchase within their borders. For those that do, however, customers can't conduct transactions without first providing a valid tax identifier.
Ship to country | Tax id type | Customer Type | Selling Entity | Required? | Description |
|---|---|---|---|---|---|
Australia | au | business | DR_IRELAND-ENTITY | No | ABN |
Austria | at | business | DR_IRELAND-ENTITY | No | VAT Number |
Bahrain | bh | business | DR_IRELAND-ENTITY | No | VAT Number |
Belarus | by | business | DR_IRELAND-ENTITY | No | VAT Number |
Belgium | be | business | DR_IRELAND-ENTITY | No | VAT Number |
Brazil | br | business | DR_BRAZIL-ENTITY | Yes | Cadastro Nacional da Pessoa Jurídica |
Brazil | br_ie | business | DR_BRAZIL-ENTITY | Yes | Inscrição Estadual |
Brazil | br_natural | individual | DR_BRAZIL-ENTITY | Yes | Cadastro de Pessoas Físicas (individuals) |
Bulgaria | bg | business | DR_IRELAND-ENTITY | No | VAT Number |
Canada | ca | business | DR_IRELAND-ENTITY | No | Canadian GST |
Canada | ca | business | C5_INC-ENTITY | No | GST Number |
Chile | cl |