Specifying a customer's type, as well as adding any tax identifiers and tax certificates associated with a customer, allows you to pass this data to a checkout and helps ensure that Digital River's tax computations are accurate.
When you create a registered checkout, Digital River uses that customer's available tax information to compute taxes on the order.
For each Checkout, Digital River determines whether any of the tax identifiers or the tax certificate attached to a Customer are applicable. We do this by analyzing the customer type, selling entity, ship-to address, and billing address, and other data points.
Refer to the page on setting the customer type.
In versions 2020-12-17
and earlier, you can use the features described in this section to manage tax identifiers. For versions 2021-02-23
and later, you can find our documentation on tax identifiers here.
Some customers have tax identifiers that allow them to purchase zero-rated goods. The government doesn’t tax the sale of zero-rated goods, but instead allows credits for the value-added tax (VAT) paid on their inputs.
Sometimes tax identifiers contained in a Customer object are used only for invoicing purposes and do not affect the taxability of an order. For example, if a customer has an Italian and a French tax identifier, we only use the one applicable to the order to compute taxes. Both tax identifiers, however, are displayed in the header of the customer's invoices and credit memos.
When you create or update a Customer, you can add one or more taxIdentifier
objects. These objects consist of a type
and a value
. The enumerated types typically comprise a lowercase, two-letter country code. The value
is dependent on the format used in each country.
Use the CountrySpecs resource to ensure that the tax identifiers entered by your customers are properly formatted.
After you submit the request, Digital River determines whether a tax identifier is required in that customer's jurisdiction, checks if the type
value is an accepted enumeration, and validates the European Union VAT number.
We use the VAT Information Exchange System (VIES) to validate EU VAT numbers. If VIES indicates the number is invalid, then we don't use it to determine an order's taxability. Instead, we simply record the VAT number on the invoice.
The following shows how to add a taxIdentifier
to the taxIdentifiers
array in a update Customer request:
curl --location --request POST 'https://api.digitalriver.com/customers/987654321' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer <API_key>' \--data-raw '{"taxIdentifiers": [{"type": "uk","value": "GB243609761"},{"type": "nl","value": "NL002458380B62"}]}'
The response returns an array of taxIdentifier
objects that are now attached to the Customer:
{"id": "987654321",..."taxIdentifiers": [{"type": "uk","value": "GB243609761"},{"type": "nl","value": "NL002458380B62"}],...}
A Customer cannot have multiple tax identifiers of the same type
. If you'd like to attach a new tax identifier to a Customer with the same type
as an existing tax identifier you must first delete the existing object.
To do this, you submit an update Customer request and set the value
you'd like to replace to null using ""
.
Make sure you format the value
without white spaces.
curl --location --request POST 'https://api.digitalriver.com/customers/987654321' \--header 'Authorization: Bearer <API_key>' \--header 'Content-Type: application/json' \--data-raw '{"taxIdentifiers": [{"type": "nl","value": ""}]}'
You then submit a second update request with the original type
and an updated value
:
curl --location --request POST 'https://api.digitalriver.com/customers/987654321' \--header 'Authorization: Bearer <API_key>' \--header 'Content-Type: application/json' \--data-raw '{"taxIdentifiers": [{"type": "nl","value": "NL001868214B01"}]}'
For each country, the following table lists the enumerated type
value. The CountrySpecs resource can help you validate the format of value
(in addition to letting you know whether a tax identifier is required in the first place).
The table also lists the associated selling entity, applicable customer type, and whether a tax identifier is required.
For the countries listed as required, customers are not allowed to conduct online transactions without first providing a valid tax identifier.
Country |
| Required? | Selling Entity | Customer Type | Description |
Australia | au | No | DR Ireland Ltd. | Business | ABN |
Austria | at | No | DR Ireland Ltd. | Business | VAT Number |
Bahrain | bh | No | DR Ireland Ltd. | Business | VAT Number |
Belarus | by | No | DR Ireland Ltd. | Business | VAT Number |
Belgium | be | No | DR Ireland Ltd. | Business | VAT Number |
Brazil | br | Yes | DR Brazil | Business | Cadastro Nacional da Pessoa JurĂdica |
Brazil | br_ie | Yes | DR Brazil | Business | Inscrição Estadual |
Brazil | br_natural | Yes | DR Brazil | Individual | Cadastro de Pessoas FĂsicas (individuals) |
Bulgaria | bg | No | DR Ireland Ltd. | Business | VAT Number |
Colombia | co | No | DR Ireland Ltd. | Business | VAT Number |
Croatia | hr | No | DR Ireland Ltd. | Business | VAT Number |
Cyprus | cy | No | DR Ireland Ltd. | Business | VAT Number |
Czech Republic | cz | No | DR Ireland Ltd. | Business | VAT Number |
Denmark | dk | No | DR Ireland Ltd. | Business | VAT Number |
Estonia | ee | No | DR Ireland Ltd. | Business | VAT Number |
Finland | fi | No | DR Ireland Ltd. | Business | VAT Number |
France | fr | No | DR Ireland Ltd. | Business | VAT Number |
Germany | de | No | DR Ireland Ltd. | Business | VAT Number |
Greece | gr | No | DR Ireland Ltd. | Business | VAT Number |
Hungary | hu | No | DR Ireland Ltd. | Business | VAT Number |
Iceland | is | No | DR Ireland Ltd. | Business | VAT Number |
India | in | No | DR Ireland Ltd. | Business | GSTIN |
India | in | No | Efulfilment Market Services Pvt. LTD | Business | GST ID |
Ireland | ie | No | DR Ireland Ltd. | Business | VAT Number |
Italy | it | No | DR Ireland Ltd. | Business | VAT Number |
Italy | it_cf | No | DR Ireland Ltd. | Individual | Codice Fiscal (individuals) |
Italy | it_natural | No | DR Ireland Ltd. | Individual | VAT Number (individuals) |
Japan | jp_offshore | No | DR Ireland Ltd. | Business | Consumption Tax ID (offshore) |
Korea | kr_offshore | No | DR Ireland Ltd. | Business | VAT Number (offshore) |
Latvia | lv | No | DR Ireland Ltd. | Business | VAT Number |
Lithuania | lt | No | DR Ireland Ltd. | Business | VAT Number |
Luxembourg | lu | No | DR Ireland Ltd. | Business | VAT Number |
Malaysia | my | No | DR Ireland Ltd. | Business | VAT Number |
Malta | mt | No | DR Ireland Ltd. | Business | VAT Number |
Netherlands | nl | No | DR Ireland Ltd. | Business | VAT Number |
New Zealand | nz | No | DR Ireland Ltd. | Business | GST ID |
Norway | no | No | DR Ireland Ltd. | Business | VAT Number |
Poland | pl | No | DR Ireland Ltd. | Business | VAT Number |
Portugal | pt | No | DR Ireland Ltd. | Business | VAT Number |
Portugal | pt_nif | No | DR Ireland Ltd. | Individual | NIF |
Romania | ro | No | DR Ireland Ltd. | Business | VAT Number |
Russia | ru | No | DR Ireland Ltd. | Business | INN |
Russia | ru_natural | No | DR Ireland Ltd. | Business | INN |
Saudi Arabia | sa | No | DR Ireland Ltd. | Business | VAT Number |
Singapore | sg | No | DR Ireland Ltd. | Business | VAT Number |
Slovakia | sk | No | DR Ireland Ltd. | Business | VAT Number |
Slovenia | si | No | DR Ireland Ltd. | Business | VAT Number |
South Africa | za | No | DR Ireland Ltd. | Business | VAT Number |
Spain | es | No | DR Ireland Ltd. | Business | VAT Number |
Sweden | se | No | DR Ireland Ltd. | Business | VAT Number |
Switzerland | ch | No | DR Ireland Ltd. | Business | VAT Number |
Taiwan | tw | Yes | DR Taiwan | Business | Unified Business Number |
Taiwan | tw_offshore | Yes | DR Ireland Ltd. | Business | Unified Business Number (offshore) |
Turkey | tr | No | DR Ireland Ltd. | Business | VAT Number |
United Arab Emirates | ae | No | DR Ireland Ltd. | Business | VAT Number |
United Kingdom | uk | No | DR Ireland Ltd. | Business | VAT Number |
​Business customers with a valid tax certificate may qualify for a tax exemption on their order. If the customer holds a tax certificate, you can associate it with the Customer by creating a TaxCertificate
object.
You are required to specify the companyName
, taxAuthority
, startDate
, endDate
and fileId
.
In both create and update Customer requests, you can use the taxCertificate
hash table to add a TaxCertificate
. For both request types, a successful response returns the updated object.
Tax certificates only apply to the United States. So the taxAuthority
is the issuing state. The value you assign should be formatted to conform to the USPS two-letter state and possession abbreviation standard. These are the same abbreviations used in the ISO 3166-2 subdivision codes.
The startDate
and endDate
values correspond to the issue and expiration dates of the tax certificate, respectively. Tax certificates, however, can be difficult to interpret. As a result, your customers might not be able to determine the appropriate dates to enter. In these cases, you should specify startDate
as the first date of the current month and endDate
as the last date of the current month. This allows us time to review the certificate, determine whether it is valid, and set the applicable dates.
You obtain the fileID
by creating a File that contains the certificate's information. The first time a customer attempts to use that tax certificate for an order, Digital River visually inspects the file to make sure it's valid. On all subsequent orders, assuming the certificate hasn't expired, the tax exemption is automatically applied.