Tax calculations

Understand how automated tax calculations work

Customer tax attributes

By specifying a customer's type, and adding any tax identifiers and certificates associated with a customer, you can ensure that Digital River's tax computations are accurate. For more information, refer to Setting customer tax attributes.

Data used to estimate and compute taxes

Digital River uses a wide-range of data points to compute taxes on an order. To ensure that we can provide an accurate tax total, we encourage you to provide as much of this data as possible.

The following table lists the attributes that are used to compute both initial tax estimates and final tax amounts:

Tax-relevant attribute

Resource

Notes

Additional Documentation

taxCode

SKU

The designated tax code of the product or service. This code is required for all SKUs you create and determines whether the product is classified as physical or digital.

Setting SKU attributes

shipFrom

Checkout

Contains the address from which the physical product is shipped. A customer can't successfully place an order for a physical product unless this information is provided.

Warehouse shipping information

shipTo

Checkout

Represents a customer's shipping address. Digital River uses the data to compute taxes on physical goods and (when the attribute is specified) on digital goods.

A customer can't successfully place an order for a physical product unless this Shipping object is provided.

The data can also be inherited from a Customer object by specifying a customerId in the Checkout.

Customer shipping information

shipping

Customer

Represents a customer's shipping address. Digital River uses the data to compute taxes on physical goods and (when the attribute is specified) on digital goods.

You can pass the object's data to a Checkout by specifying a customerId. This fulfills the requirement to provide a shipTo value for physical goods even when the value is not explicitly set in the Checkout.

Customer address information

purchaseLocation

Checkout

Use this value when customers have yet to supply either the Checkout's shipTo value that is required to successfully submit an order for physical goods or the owner.address value of a Source that is necessary for digital goods.

Setting the purchase location

sources[].owner.address

Customer

Represents the billing address for the owner of a payment method. The object is used to compute taxes on digital orders. However, when provided, the Checkout'sshipTo value or the Customer's shipping value takes precedence over the billing address.

taxIdentifiers

Customer

Allows qualified customers to purchase zero-rated goods.

Tax identifiers

taxCertificates

Customer

Allows qualified customers to make tax exempt purchases.

Tax certificates

type

Customer

Allows you to support tax exemption and zero-rated purchases for business customers.

If you want to purchase zero-rated goods or use tax exemptions on orders, then set the value to business. Setting the value to individual nullifies the use of taxIdentifiers and taxCertificates for tax computation purposes. These attributes, however, may still be used for reporting and invoicing.

Customer type

customerType

Checkout

Same behavior as the Customer type attribute (see above). However, the value set in the Checkout always overrides the one in the Customer object.

Creating checkouts

taxInclusive

Checkout

Lets Digital River know whether to subtract taxes from or add taxes to the price you specify for each SKU in the items array.

Configuring taxes

Tax estimation and computation workflow

Example: Getting a tax estimate

As the workflow explains, a purchaseLocation can generate a tax estimate when the customer has not yet provided a shipping or billing address. The following shows two simple create Checkout requests, with and without the purchaseLocation value provided:

You're only required to provide a postalCode for purchase locations within the United States.

curl (no purchaseLocation provided)
curl (purchaseLocation provided)
curl (no purchaseLocation provided)
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
--header 'Content-Type: text/plain' \
--data-raw '{
"currency": "USD",
"items": [
{
"skuId": "05081978",
"price": 100.00,
"quantity": 1
}
]
}'
curl (purchaseLocation provided)
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
--header 'Content-Type: text/plain' \
--data-raw '{
"currency": "USD",
"items": [
{
"skuId": "05081978",
"price": 100.00,
"quantity": 1
}
],
"purchaseLocation": {
"country": "US",
"state": "MN",
"postalCode": "55116"
}
}'

When the purchaseLocation is provided, the response returns a tax estimate at both the item and the Checkout level:

JSON (no purchaseLocation provided)
JSON (purchaseLocation provided)
JSON (no purchaseLocation provided)
{
"id": "177375830336",
...
"totalAmount": 100.0,
"subtotal": 100.0,
"totalFees": 0.0,
"totalTax": 0.0,
"totalDuty": 0.0,
"totalDiscount": 0.0,
"totalShipping": 0.0,
"items": [
{
"skuId": "05081978",
"amount": 100.0,
"quantity": 1,
"tax": {
"rate": 0.0,
"amount": 0.0
}
}
],
"purchaseLocation": {
"country": "US",
"state": "MN",
"postalCode": "55116"
},
...
}
JSON (purchaseLocation provided)
{
"id": "177374720336",
...
"totalAmount": 107.88,
"subtotal": 100.0,
"totalFees": 0.0,
"totalTax": 7.88,
"totalDuty": 0.0,
"totalDiscount": 0.0,
"totalShipping": 0.0,
"items": [
{
"skuId": "05081978",
"amount": 100.0,
"quantity": 1,
"tax": {
"rate": 0.07875,
"amount": 7.88
}
}
],
"purchaseLocation": {
"country": "US",
"state": "MN",
"postalCode": "55116"
},
...
}

Example: Computing taxes on a physical good

As indicated in the workflow, if an order contains a physical good, taxes are only computed when both a ship-to and ship-from address are provided.

In the following example, both requests contain a ship-to address because the Checkouts are associated with a Customer that has a specified shipping.address . The request on the first tab, however, doesn't contain a shipFrom address while the second request includes the value.

curl (shipFrom not included)
curl (shipFrom included)
curl (shipFrom not included)
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
--header 'Content-Type: text/plain' \
--data-raw '{
"currency": "USD",
"customerId": "987654321",
"items": [
{
"skuId": "05081978",
"price": 100.00,
"quantity": 1
}
],
...
}'
curl (shipFrom included)
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
--header 'Content-Type: text/plain' \
--data-raw '{
"currency": "USD",
"customerId": "987654321",
"shipFrom": {
"address": {
"line1": "350 S 5th St",
"city": "Minneapolis",
"postalCode": "55415",
"state": "MN",
"country": "US"
}
},
"items": [
{
"skuId": "05081978",
"price": 100,
"quantity": 1
}
],
...
}'

When the respective checkoutId values returned in the response are then passed to a create Order request, taxes are successfully computed on the Order with a shipFrom but the one that omits the value returns a bad request.

For each element in the items array, the tax.rate is returned in an unmodified decimal format.

JSON (shipFrom not included)
JSON (shipFrom included
JSON (shipFrom not included)
{
"type": "bad_request",
"errors": [
{
"code": "missing_parameter",
"parameter": "shipFrom.address",
"message": "A parameter is missing."
}
]
}
JSON (shipFrom included
{
"id": "177419440336",
...
"shipTo": {
"address": {
"line1": "10380 Bren Rd W",
"line2": "string",
"city": "Minnetonka",
"postalCode": "55129",
"state": "MN",
"country": "US"
},
"name": "Jane Doe",
"phone": "952-111-1111",
"email": "jdoe@digitalriver.com",
"organization": "Digital River"
},
"shipFrom": {
"address": {
"line1": "350 S 5th St",
"line2": "string",
"city": "Minneapolis",
"postalCode": "55415",
"state": "MN",
"country": "US"
}
},
"totalAmount": 113.5,
"subtotal": 105.95,
"totalFees": 0.0,
"totalTax": 7.55,
"totalDuty": 0.0,
"totalDiscount": 0.0,
"totalShipping": 5.95,
"items": [
{
"itemId": "96375050336",
"skuId": "05081978",
"amount": 100.0,
"quantity": 1,
"state": "created",
"stateTransitions": {
"created": "2020-05-19T21:15:11Z"
},
"tax": {
"rate": 0.07125,
"amount": 7.13
}
}
],
...
}