Setting tax-related attributes

Learn how to set tax-related attributes on the Customer resource

By specifying a customer's type, as well as adding any tax identifiers and certificates associated with the customer, you help ensure that Digital River's tax computations are accurate.

Customer type

The type attribute allows you to support tax exemptions for business customers.

Setting the customer type

When you create or update a Customer, you can set the type of customer as either business or individual.

cURL
cURL
curl https://api.digitalriver.com/customers \
-u sk_test_<API_key>: \
-d type="business"

The response returns a Customer object with the type you set in the request:

JSON
JSON
{
"id": "516918920336",
...
"type": "business",
...
}

In the Checkouts resource, you can also indicate whether an order is placed by a business or an individual. This is done with the customerType attribute. Just remember that the value specified in the Checkout overrides the one contained in the Customer object.

Tax identifiers

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 consist of a lowercase, two-letter country code.

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 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 list of member states on VIES still currently includes the United Kingdom.

The following shows how to add a TaxIdentifier object 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 object:

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 TaxIdentifier to a Customer with the same type as an existing TaxIdentifier, you must first delete the existing object.

To do this, you submit an update Customer request and set the value of the TaxIdentifier 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 and one or more regular expressions that can be used to validate the value.

The table also lists the associated selling entity, applicable customer type, and whether the 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

Regular Expression(s) to Validate value

Required?

Selling Entity

Customer Type

Description

Australia

au

^\d\d\d\d\d\d\d\d\d\d\d$

^ABN\d\d\d\d\d\d\d\d\d\d\d$

^\d\d\d\d\d\d\d\d\d\d\d\d\d\d$

^ABN\d\d\d\d\d\d\d\d\d\d\d\d\d\d$

^ARN\d\d\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

ABN

Austria

at

^ATU\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Bahrain

bh

^2\d\d\d\d\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Belarus

by

^\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Belgium

be

^BE\d\d\d\d\d\d\d\d\d\d$

^BE0\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Brazil

br

^\d\d\d\d\d\d\d\d\d\d\d\d\d\d$

Yes

DR Brazil

Business

Cadastro Nacional da Pessoa Jurídica

Brazil

br_ie

^(ISENTO|\d{8,13})$

Yes

DR Brazil

Business

Inscrição Estadual

Brazil

br_natural

^\d\d\d\d\d\d\d\d\d\d\d$

Yes

DR Brazil

Individual

Cadastro de Pessoas Físicas (individuals)

Bulgaria

bg

^BG\d\d\d\d\d\d\d\d\d$ ^BG\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Colombia

co

^\d{6,11}$

No

DR Ireland Ltd.

Business

VAT Number

Croatia

hr

^HR\d\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Cyprus

cy

^CY\d\d\d\d\d\d\d\d[A-Z]$

No

DR Ireland Ltd.

Business

VAT Number

Czech Republic

cz

^CZ\d\d\d\d\d\d\d\d$ ^CZ\d\d\d\d\d\d\d\d\d$ ^CZ\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Denmark

dk

^DK\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Estonia

ee

^EE\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Finland

fi

^FI\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

France

fr

^FR[A-Z\d][A-Z\d]\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Germany

de

^DE\d\d\d\d\d\d\d\d\d$ ^DE\d\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Greece

gr

^EL\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Hungary

hu

^HU\d\d\d\d\d\d\d\d$ ^HU\d\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Iceland

is

^\d\d\d\d\d$

^\d\d\d\d\d\d$

^VSK\d\d\d\d\d$ ^VSK\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

India

in

^(0[1-9]|[1-2][0-9]|3[0-7])([A-Z]\d){13}$

No

DR Ireland Ltd.

Business

GSTIN

India

in

^(0[1-9]|[1-2][0-9]|3[0-7])([A-Z]\d){13}$

No

Efulfilment Market Services Pvt. LTD

Business

GST ID

Ireland

ie

^IE\d\d\d\d\d\d\d[A-Z]$ ^IE\d\d\d\d\d\d\d[A-Z][A-Z]$

^IE\d[A-Z]\d\d\d\d\d[A-Z]$ ^IE\d\d\d\d\d\d[A-Z]$

No

DR Ireland Ltd.

Business

VAT Number

Italy

it

^IT\d\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Italy

it_cf

^[A-Z\d][A-Z\d][A-Z\d][A-Z\d][A-Z\d][A-Z\d][A-Z\d][A-Z\d][A-Z\d][A-Z\d][A-Z\d][A-Z\d][A-Z\d][A-Z\d][A-Z\d][A-Z\d]$

No

DR Ireland Ltd.

Individual

Codice Fiscal (individuals)

Italy

it_natural

^IT\d\d\d\d\d\d\d\d\d\d\d$ ^\d\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number (individuals)

Japan

jp_offshore

^\d\d\d\d\d$

^\d\d\d\d\d\d\d\d$ ^\d\d\d\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

Consumption Tax ID (offshore)

Korea

kr_offshore

^\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number (offshore)

Latvia

lv

^LV\d\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Lithuania

lt

^LT\d\d\d\d\d\d\d\d\d$ ^LT\d\d\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Luxembourg

lu

^LU\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Malaysia

my

^[A-Z]\d\d\d\d\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Malta

mt

^MT\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Netherlands

nl

^NL\d\d\d\d\d\d\d\d\dB\d\d$

No

DR Ireland Ltd.

Business

VAT Number

New Zealand

nz

^\d\d\d\d\d\d\d\d$ ^\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

GST ID

Norway

no

^NO\d\d\d\d\d\d\d\d\dMVA$ ^\d\d\d\d\d\d\d\d\dMVA$

No

DR Ireland Ltd.

Business

VAT Number

Poland

pl

^PL\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Portugal

pt

^PT\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Portugal

pt_nif

^\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Individual

NIF

Romania

ro

^RO\d{2,10}$

No

DR Ireland Ltd.

Business

VAT Number

Russia

ru

^\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

INN

Russia

ru_natural

^\d\d\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

INN

Saudi Arabia

sa

^3\d\d\d\d\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Singapore

sg

^[A-Z\d][A-Z\d]\d\d\d\d\d\d\d[A-Z\d]$

^T\d\d[A-Z][A-Z\d]\d\d\d\d[A-Z\d]$ ^\d\d\d\d\d\d\d\d[A-Z\d]$ ^\d\d\d\d\d\d\d\d\d[A-Z\d]$ ^S\d\d[A-Z][A-Z\d]\d\d\d\d[A-Z\d]$

No

DR Ireland Ltd.

Business

VAT Number

Slovakia

sk

^SK\d\d\d\d\d\d\d\d\d\d$ ^SK\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Slovenia

si

^SI\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

South Africa

za

^\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Spain

es

^ES[A-Z\d]\d\d\d\d\d\d\d[A-Z\d]$

No

DR Ireland Ltd.

Business

VAT Number

Sweden

se

^SE\d\d\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Switzerland

ch

^CH\d\d\d\d\d\d$ ^\d\d\d\d\d\d\d\d\d$ ^CHE\d\d\d\d\d\d\d\d\d$ ^CHE\d\d\d\d\d\d\d\d\dHRMWST$ ^CHE\d\d\d\d\d\d\d\d\dMWST$ ^CHE\d\d\d\d\d\d\d\d\dRCIVA$ ^CHE\d\d\d\d\d\d\d\d\dRCTVA$ ^CHE\d\d\d\d\d\d\d\d\dIVA$ ^CHE\d\d\d\d\d\d\d\d\dTVA$

No

DR Ireland Ltd.

Business

VAT Number

Taiwan

tw

^\d\d\d\d\d\d\d\d$

Yes

DR Taiwan

Business

Unified Business Number

Taiwan

tw_offshore

^\d\d\d\d\d\d\d\d$

Yes

DR Ireland Ltd.

Business

Unified Business Number (offshore)

Turkey

tr

^\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

United Arab Emirates

ae

^1\d\d\d\d\d\d\d\d\d\d\d\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

United Kingdom

uk

^GB\d\d\d\d\d\d\d\d\d$ ^GB\d\d\d\d\d\d\d\d\d\d\d\d$ ^GB[A-Z][A-Z]\d\d\d$

No

DR Ireland Ltd.

Business

VAT Number

Tax certificates

Business entities with valid tax certificates may qualify for a tax exemption on their order. If the customer holds a tax certificate, you can associate it with the Customer by using aTaxCertificate object.

Adding tax certificates

In a create new Customer request, you can add a single TaxCertificate object. In an update Customer request, you're allowed to use the taxCertificates array to add one or more objects. In both cases, a successful response returns an array of taxCertificates.

The only required attribute in the object is fileId. You obtain this identifier 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.

Since tax certificates only apply to the United States, the taxAuthority attribute is assigned to the issuing state.

Passing tax information to a Checkout

When you create or update a Checkout and provide a customerId, Digital River uses that customer's available tax information to compute taxes on the order.

For each Checkout, Digital River determines if any of the tax identifiers or certificates attached to a Customer are applicable. We do this by analyzing the customer type, selling entity, ship-to/bill-to address, and other data points.

For more information on how this works, refer to Tax calculations.