Tax identifiers
Learn how to manage and apply tax identifiers.
Last updated
Learn how to manage and apply tax identifiers.
Last updated
In 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 will no longer be available. For assistance with migrating your data, contact us.
For versions 2020-12-17
and earlier, refer to the section on the .
The Digital River API uses tax identifiers for .
When you , we initiate a . Once the transitions to the appropriate , assuming it , it can be used to determine its taxability.
To , you can . Alternatively, you can and .
Your checkout flow should also consider that some . When a customer in one of these countries doesn't supply a tax identifier, we block the order and of the problem.
You can use our test tax identifiers when you're ready to evaluate your integration.
In most value-added tax (VAT) schemes, domestic sales to business customers are assessed tax, and customers then get a credit for this tax paid when they complete their monthly or quarterly VAT return. Customers need the invoice to display their tax identifier to obtain this credit.
Alternatively, cross-border sales to business customers are not assessed tax in most VAT schemes. Instead, in a reverse charge practice, customers self-assess the tax while simultaneously getting a ta credit when they complete their monthly or quarterly VAT return. In these cases, the tax identifier is used to determine whether or not a reverse charge applies to a specific order.
Additionally, in a limited number of cases, tax identifiers are collected because they are for invoicing purposes.
In the Digital River APIs, a tax identifier is always represented by a . Additionally, the object will contain attributes that indicate its , its , and .
Sometimes, a tax identifier may include a , a , and an .
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
VIES no longer verifies VAT numbers from Great Britain.
If VIES indicates a tax identifier is not_valid
, then we don't use it to determine an order's taxability.
We also apply validation algorithms for certain countries defined by the local authority that issued the number.
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.
If you were to submit another POST /orders
request with the same settings—the only difference is that in the new request, you specified ashipTo.country
of DK
(Denmark)—you'd receive a 409 Conflict
response. Customers holding tax identifiers issued by one country can't apply them to orders shipped to a different country.
If no tax identifiers are directly attached to a checkout or invoice and the customer is a guest, we don't use any tax identifiers when computing taxes.
When you configure the element with a payment session identifier, we filter out tax identifiers that do not apply to the transaction.
For registered checkouts, any tax identifiers directly attached must be associated with the customer placing the order. If any are held by a different customer, the following 409 Conflict
response is returned:
When using a customer's saved tax identifier, determine whether it exists. If you associate a tax identifier with a checkout, but the object has been deleted, we return the following error:
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 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.
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.
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 do not agree.
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.
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
individual
DR_IRELAND-ENTITY
No
RUT
Chile
cl
business
DR_IRELAND-ENTITY
No
RUT
Colombia
co
business
DR_IRELAND-ENTITY
No
VAT Number
Croatia
hr
business
DR_IRELAND-ENTITY
No
VAT Number
Cyprus
cy
business
DR_IRELAND-ENTITY
No
VAT Number
Czech Republic
cz
business
DR_IRELAND-ENTITY
No
VAT Number
Denmark
dk
business
DR_IRELAND-ENTITY
No
VAT Number
Estonia
ee
business
DR_IRELAND-ENTITY
No
VAT Number
Finland
fi
business
DR_IRELAND-ENTITY
No
VAT Number
France
fr
business
DR_IRELAND-ENTITY
No
VAT Number
Germany
de
business
DR_IRELAND-ENTITY
No
VAT Number
Greece
gr
business
DR_IRELAND-ENTITY
No
VAT Number
Hungary
hu
business
DR_IRELAND-ENTITY
No
VAT Number
Iceland
is
business
DR_IRELAND-ENTITY
No
VAT Number
India
in
business
DR_IRELAND-ENTITY
No
GSTIN
Indonesia
id
business
DR_IRELAND-ENTITY
No
NPWP
Ireland
ie
business
DR_IRELAND-ENTITY
No
VAT Number
Isle of Man
uk
business
DR_IRELAND-ENTITY
No
VAT Number
Isle of Man
uk
business
DR_UK-ENTITY
No
VAT Number
Italy
it
business
DR_IRELAND-ENTITY
No
VAT Number
Italy
it_cf
individual
DR_IRELAND-ENTITY
No
Codice Fiscal (individuals)
Italy
it_natural
individual
DR_IRELAND-ENTITY
No
VAT Number (individuals)
Japan
jp
business
DR_JAPAN-ENTITY
No
TIN
Japan
jp_offshore
business
DR_IRELAND-ENTITY
No
Consumption Tax ID (offshore)
Kenya
ke
business
DR_IRELAND-ENTITY
Yes
PIN
Korea
kr_offshore
business
DR_IRELAND-ENTITY
No
VAT Number (offshore)
Latvia
lv
business
DR_IRELAND-ENTITY
No
VAT Number
Lithuania
lt
business
DR_IRELAND-ENTITY
No
VAT Number
Luxembourg
lu
business
DR_IRELAND-ENTITY
No
VAT Number
Malaysia
my
business
DR_IRELAND-ENTITY
No
VAT Number
Malta
mt
business
DR_IRELAND-ENTITY
No
VAT Number
Mexico
mx_natural
individual
DR_IRELAND-ENTITY
No
RFC
Mexico
mx
business
DR_IRELAND-ENTITY
No
RFC
Monaco
fr
business
DR_IRELAND-ENTITY
No
VAT Number
Netherlands
nl
business
DR_IRELAND-ENTITY
No
VAT Number
New Zealand
nz
business
DR_IRELAND-ENTITY
No
GST ID
Norway
no
business
DR_IRELAND-ENTITY
No
VAT Number
Philippines
ph
business
DR_IRELAND-ENTITY
No
TIN
Poland
pl
business
DR_IRELAND-ENTITY
No
VAT Number
Portugal
pt
business
DR_IRELAND-ENTITY
No
VAT Number
Portugal
pt_nif
individual
DR_IRELAND-ENTITY
No
NIF
Romania
ro
business
DR_IRELAND-ENTITY
No
VAT Number
Russia
ru
business
DR_IRELAND-ENTITY
No
INN
Russia
ru_natural
business
DR_IRELAND-ENTITY
No
INN
Saudi Arabia
sa
business
DR_IRELAND-ENTITY
No
VAT Number
Singapore
sg
business
DR_IRELAND-ENTITY
No
VAT Number
Slovakia
sk
business
DR_IRELAND-ENTITY
No
VAT Number
Slovenia
si
business
DR_IRELAND-ENTITY
No
VAT Number
South Africa
za
business
DR_IRELAND-ENTITY
No
VAT Number
Spain
es
business
DR_IRELAND-ENTITY
No
VAT Number
Sweden
se
business
DR_IRELAND-ENTITY
No
VAT Number
Switzerland
ch
business
DR_IRELAND-ENTITY
No
VAT Number
Taiwan
tw
business
DR_TAIWAN-ENTITY
Yes
Unified Business Number
Taiwan
tw_offshore
business
DR_IRELAND-ENTITY
Yes
Unified Business Number (offshore)
Thailand
th
business
DR_IRELAND-ENTITY
No
VAT Number
Turkey
tr
business
DR_IRELAND-ENTITY
No
VAT Number
Ukraine
ua
business
DR_IRELAND-ENTITY
No
VAT Number
United Arab Emirates
ae
business
DR_IRELAND-ENTITY
No
VAT Number
United Kingdom
uk
business
DR_IRELAND-ENTITY
No
VAT Number
United Kingdom
uk
business
DR_UK-ENTITY
No
VAT Number
Country
type
value
Belgium
be
BE0000000000
, BE1234567890
Germany
de
DE000000000
, DE123456789
Italy
it
or it_natural
IT00000000000
, IT12345678901
A tax identifier is always returned with a unique id
. Besides using this identifier to and a tax identifier, you can use it to or .
The customerId
is only returned when the tax identifier is .
The type
attribute identifies the country that issued the tax identifier. The typically consist of a lowercase, two-letter country code. However, some countries have more than one
and 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 , you can use the to help you validate its format. This element indicates if a tax identifier is required in the purchase country.
A tax identifier can be in a state of pending
, not_valid
, and verified
. Its state is dependent on where it is in the .
Each state transition causes a corresponding to be emitted whose data.object
consists of the tax identifier.
A tax identifier in any state can be or . 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 formatted date and time is returned in the stateTransitions
hash table.
During the tax identifier , we sometimes can obtain the holder's verifiedName
and verifiedAddress
.
A tax identifier always contains a createdTime
. When a tax identifier is , its or the are added, then the time these events occurred is reflected in the updatedTime
field.
When a 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:
Before , you can .
For European Union tax identifiers, commonly known as Value Added Tax (VAT) numbers, we use the to validate the customer's data.
After a POST /tax-identifiers
is submitted, Digital River provides VIES with the data submitted in the request. VIES, in turn, transmits our validation query to the relevant member state's database. 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 . VIES then relays this information back to us.
If VIES successfully responds before the , then the transitions to either verified
or not_valid
. This causes either a tax_identifier.verified
or tax_identifier.not_valid
to fire. The tax identifier is immediately applied to the order if the number is verified.
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 creation. We treat a pending
tax identifier as being verified
in these cases until we know otherwise. In other words, pending
and verified
tax identifiers are both used by Digital River to determine an taxability.
A tax identifier's information is displayed on , regardless of its state
.
Before a tax identifier can be successfully applied to a , the , the , the , and the country (a country for or a country for ) must agree.
With a few , most countries only allow business
customers to apply tax identifiers.
Digital River first searches for directly . This is true whether you're checking out a or a .
However, when it's a registered checkout and that that are applicable, and those tax identifiers are not yet attached, we apply them as well.
Before they are , we allow you to information provided by customers. Once validated, you can use the to , , , and them.
You can also and then later, if necessary, . To or tax identifiers, you must delete the existing object before creating a new one.
You can use the tax identifier element to validate the format entered by a customer and determine whether a tax identifier is required and applicable to the transaction. To create the element, you must combine the identifier, , and ship to/bill to returned in a or .
You use the method to create a tax identifier. In the request, you must specify both a . Once the request is submitted, we initiate a .
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 of the tax identifier indicates it's still being .
You can delete a tax identifier by submitting a 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 it may have been associated with.
Once a tax identifier is deleted, if you later attempt to , you'll get the following 404 Not Found
error.
Once you've , you can use the POST /customers/{id}/tax-identifiers/{taxId}
method to attach it to an existing customer. This request returns the and triggers a customer.tax_identifier.created
event. The event's data.object
also represents the tax identifier.
The customerId
attribute is populated in the response since it's now associated with a customer. The following example response shows a British (uk
) issued tax identifier in a . When the customer next makes an , this tax identifier will automatically apply to the order.
To disassociate a tax identifier from a customer, send a through the . A successful request means that when the customer creates 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 , but it's already attached to a different customer, you'll receive a 409 Conflict
response.
In these cases, you must first , create a new object with an identical , and then assign it to the desired customer.
Customers can have multiple tax identifiers but not more than one of the same . So, if you want to attach a new tax identifier to a customer, but that customer already holds one with that type
, you must first . Once you've consumed either the 204 No Content
response or the tax_identifier.deleted
event, your integration can and .
Once they are created, there are two ways to apply tax identifiers to a purchase. You can either . Or you can .
In either case, during the checkout process, we determine whether the and .
You should also ensure you pass the necessary information to correctly .
When checking out , 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 send the object's identifier in the taxIdentifiers
array.
A successful response returns a checkout or invoice that contains an array of . The indicates whether it will be used to determine an order's taxability, depending on .
Before attaching a tax identifier, you should .
This information in this section is only applicable to 2021-03-23
and earlier of the Digital River APIs.
For more information, refer to on the customers page.
When you create a , we search for tax identifiers . 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 .
For example, let's say a customer holds a tax identifier of type dk
(Denmark) and another type uk
(Great Britain). In a POST/checkouts
request, you and specify a 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 .
If you attach a tax identifier to the checkout and the are not met, you receive an error:
country
: The ship-to country for or the bill-to country for
entity
: The of the transaction
customerType
: The making the purchase
The applicability
block is especially useful with . But, if you decide not to , you can also use applicability
with .
During , 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 , make a request to retrieve the customer's saved tax identifiers.
In registered checkouts, you can send an empty taxIdentifiers
array to .
Next, use the checkout's (or 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.
After that, display this filtered list to the customer. Once the customer selects an option, .
If a registered or supplies new tax identifier information during checkout, send the necessary data in a request. You can then use applicability
in the response to determine whether the checkout contains the matching country, selling entity, and customer type values.
We suggest .
When you want to inform us that no tax identifiers should be applied to a , submit a create or update request with an empty taxIdentifiers
array. This indicates that none of the customer's should be used to determine the order's taxability.
On the other hand, not including thetaxIdentifiers
array in a registered checkout has no effect. In this scenario, we any applicable tax identifiers saved to the customer's account.
In , 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 orders from being placed.
During checkout, you can use the 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 of individual
and a of BR
(Brazil). In that same request, if no tax identifiers with a of br_natural
are either or , you'll receive a 409 Conflict
response.
After fulfilling an order and receiving the necessary events, you can . When a applies a tax identifier, the company name must be displayed on these invoices. To ensure this happens, you must set the organization
parameter when for orders that contain .
The following table lists the combination of country, , , and that must be aligned before a tax identifier can be applied to an order.
As the table indicates, most countries don't require a tax identifier when purchasing online within their borders. For those that do, however, without first providing a valid tax identifier.
In the , the following pairs allow you to create tax identifiers:
The Italian values can be paired with either it
or it_natural
. The type
you specify depends on whether you're to a test purchase made by an . Once you , you can always reference to determine its .