Tax calculations

Understand how automated tax calculations work.

Supplying data 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 you can set that influence how Digital River computes both initial tax estimates and final tax amounts:
Tax-relevant attribute
Resource
Notes
taxCode
SKU
The designated tax code of the product or service. Digital River uses the value you provide to classify the product as digital or physical. 
shipFrom
Checkout
Represents the address from which the physical product is shipped. 

A customer must provide this information to successfully place an order that contains a physical product.  
shipTo
Checkout
Represents an order's ship to address. Digital River uses this data to compute taxes on physical goods and (when the attribute is specified) on digital goods.
​
A customer must provide this information to successfully place an order that contains a physical product. 
​
The data can also be inherited from a Customer object by specifying a customer identifier in the Checkout. 
shipping
Customer
Represents a customer's ship to 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 customer identifier. This fulfills the requirement to provide a shipTo value for physical goods even when the value is not explicitly set in the Checkout. 
purchaseLocation
Checkout
Use a purchase location 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 billing address that is necessary for digital goods.
sources[].owner.address
Customer
Represents a billing address for a payment method and is used to compute taxes on digital orders. 
​
You set the address when creating a source. 

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.
taxCertificates
Customer
Allows qualified customers to make tax exempt purchases.
type
Customer
Providing a customer type allows you to support tax exemption and zero-rated purchases for business customers. 

Setting the value to individual nullifies the use of tax identifiers and tax certificates for tax computation purposes. These attributes, however, may still be used for reporting and invoicing. 
customerType
Checkout
This attribute is equivalent to the type attribute in the Customer resource. However, the value set in the Checkout always overrides the one in the Customer object. 
taxInclusive
Checkout
Lets Digital River know whether to subtract taxes from or add taxes to the price you specify for each SKU when describing items in a Checkout.
Tax estimation and computation workflow
The following provides a high-level overview of how Digital River uses the SKU tax code to classify a product as digital or physical. This then determines the address requirements of the order. If these are met, taxes can be computed and the order can be placed. Otherwise, depending on the stage of the checkout process, the order is either blocked or a tax estimate is provided to the customer.  
Using purchase location to get a tax estimate
As the workflow explains, a purchase location 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"
    },
...
}
​

Selling entities

Landed costs

Last updated 2 weeks ago

Tax-relevant attribute	Resource	Notes
taxCode	SKU	The designated tax code of the product or service. Digital River uses the value you provide to classify the product as digital or physical.
shipFrom	Checkout	Represents the address from which the physical product is shipped. A customer must provide this information to successfully place an order that contains a physical product.
shipTo	Checkout	Represents an order's ship to address. Digital River uses this data to compute taxes on physical goods and (when the attribute is specified) on digital goods. A customer must provide this information to successfully place an order that contains a physical product. The data can also be inherited from a Customer object by specifying a customer identifier in the Checkout.
shipping	Customer	Represents a customer's ship to 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 customer identifier. This fulfills the requirement to provide a `shipTo` value for physical goods even when the value is not explicitly set in the Checkout.
purchaseLocation	Checkout	Use a purchase location 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 billing address that is necessary for digital goods.
sources[].owner.address	Customer	Represents a billing address for a payment method and is used to compute taxes on digital orders. You set the address when creating a source. However, when provided, the Checkout's`shipTo` value or the Customer's `shipping` value takes precedence over the billing address.
taxIdentifiers	Customer	Allows qualified customers to purchase zero-rated goods.
taxCertificates	Customer	Allows qualified customers to make tax exempt purchases.
type	Customer	Providing a customer type allows you to support tax exemption and zero-rated purchases for `business` customers. Setting the value to `individual` nullifies the use of tax identifiers and tax certificates for tax computation purposes. These attributes, however, may still be used for reporting and invoicing.
customerType	Checkout	This attribute is equivalent to the type attribute in the Customer resource. However, the value set in the Checkout always overrides the one in the Customer object.
taxInclusive	Checkout	Lets Digital River know whether to subtract taxes from or add taxes to the price you specify for each SKU when describing items in a Checkout.

Tax calculations

Supplying data to estimate and compute taxes

Tax estimation and computation workflow

Using purchase location to get a tax estimate

​