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. 
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
Additional  Documentation
taxCode
SKU
The designated tax code of the product or service. This code is required for all SKUs you create.
​Setting SKU attributes​
partNumber
SKU
The manufacturer part number. 

For SKUs that represent a physical product, you're required to provide a value. If you don't specify a value, then we consider the SKU to be a digital product. 
​
Digital River needs to know the product is physical to determine the selling entity which then affects the tax workflow and whether landed costs are applicable.  
​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 parameter 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
            }
        }
    ],
...
}

Handling delayed orders

Sources

Last updated 6 days ago

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.	Setting SKU attributes
partNumber	SKU	The manufacturer part number. For SKUs that represent a physical product, you're required to provide a value. If you don't specify a value, then we consider the SKU to be a digital product. Digital River needs to know the product is physical to determine the selling entity which then affects the tax workflow and whether landed costs are applicable.	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 parameter 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'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.	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