Setting tax-related attributes

Learn how to set the customer type, tax certificates, and tax identifiers.

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.

Passing tax information to a checkout

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.

Customer type

Refer to the page on setting the customer type.

Tax identifiers

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.

Adding tax identifiers

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
cURL
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:

JSON
JSON
{
"id": "987654321",
...
"taxIdentifiers": [
{
"type": "uk",
"value": "GB243609761"
},
{
"type": "nl",
"value": "NL002458380B62"
}
],
...
}

Replacing a tax identifier

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
curl
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
curl
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"
}
]
}'

Supported tax identifiers

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

type

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

Tax certificates

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.

Adding a tax certificate

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.