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

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.

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"
        }
    ],
...
}

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 "".

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

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.

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.