Configuring taxes

Learn how to properly configure taxes on items and shipping in a Checkout request

Digital River automatically calculates taxes for you. All you have to do is tell us whether taxes are included in the item and shipping amounts you provide.

To do this, use the taxInclusive parameter at the Checkout level. This value lets us know whether to subtract taxes from or add taxes to the items[].price and shippingChoice.amount values you provide in the request.

In the Checkout response , we return the tax.rate and tax.amount on the shippingChoiceand each element in the items array.

Getting item taxes

The tax.amount on each element in the items array is calculated by Digital River and returned in the Checkout response. Just make sure to tell us whether or not the items.price you provide in the request includes taxes. You do this by setting the taxInclusive parameter.

If you set taxInclusive to true, for each element in the array, Digital River subtracts the tax.amount based on the items.priceyou provide. If you set the parameter to false, we add the tax on each item to its price.

Getting shipping taxes

Shipping taxes are also automatically calculated. You just need to tell us whether the shippingChoice.amount you provide in the request already has taxes built in.

If you set taxInclusive to true, then Digital River subtracts the shippingChoice.tax.amount we calculate based on the shippingChoice.amountyou provide. If the parameter is false, we add calculated taxes to the amount you provided.

In either case, we'll use the shippingChoice.tax.amount when aggregating the total taxes for the order.

Example: Setting taxInclusive to true

The following POST /checkout request sets taxInclusive to true:

cURL
cURL
curl https://api.digitalriver.com/checkouts \
-u sk_test_db9682a2-b04a-4e94-8e11-35fe8ec0b324: \
-d currency=usd \
-d taxInclusive=true \
-d items[0][skuId]=09062016 \
-d items[0][price]=10.00 \
-d items[0][quantity]=3 \
-d items[0][skuId]=11141976 \
-d items[0][price]=8.00 \
-d items[0][quantity]=2 \
-d shipTo[address][line1]=10380 Bren Road West \
-d shipTo[address][city]=Minnetonka \
-d shipTo[address][postalCode]=55343 \
-d shipTo[address][state]=MN \
-d shipTo[address][country]=US \
-d shippingChoice[amount]=5.00 \
-d shippingChoice[description]="USPS: Priority (1 day delivery)" \
-d shippingChoice[serviceLevel]= "SG"

For the items and the shippingChoice, the taxable amount is calculated and subtracted from the amount you provided in the request:

JSON
JSON
"items": [
{
"skuId": "09062016",
"amount": 27.9,
"quantity": 3,
"tax": {
"rate": 0.07525,
"amount": 2.1
}
},
{
"skuId": "11141976",
"amount": 14.88,
"quantity": 2,
"tax": {
"rate": 0.07525,
"amount": 1.12
}
}
],
"shippingChoice": {
"amount": 4.65,
"description": "USPS: Priority (1 day delivery)",
"serviceLevel": "SG",
"tax": {
"rate": 0.076,
"amount": 0.35
}
},

The subtotal is the pre-tax cost of the items and shipping. The totalTax is determined by adding the combined taxes for the items and shipping. The totalAmount equals the subTotal plus the totalTax.

JSON
JSON
"totalAmount": 51.00,
"subtotal": 47.43,
"totalFees": 0.0,
"totalTax": 3.57,
"totalDuty": 0.0,
"totalDiscount": 0.0,
"totalShipping": 5.00,

Example: Setting taxInclusive to false

The following POST /checkout request sets taxInclusive to false:

The default value for taxInclusive is false

cURL
cURL
curl https://api.digitalriver.com/checkouts \
-u sk_test_db9682a2-b04a-4e94-8e11-35fe8ec0b324: \
-d currency=usd \
-d taxInclusive=false \
-d items[0][skuId]=09062016 \
-d items[0][price]=10.00 \
-d items[0][quantity]=3 \
-d items[0][skuId]=11141976 \
-d items[0][price]=8.00 \
-d items[0][quantity]=2 \
-d shipTo[address][line1]=10380 Bren Road West \
-d shipTo[address][city]=Minnetonka \
-d shipTo[address][postalCode]=55343 \
-d shipTo[address][state]=MN \
-d shipTo[address][country]=US \
-d shippingChoice[amount]="5.00" \
-d shippingChoice[description]="USPS: Priority (1 day delivery)" \
-d shippingChoice[serviceLevel]= "SG"

For the items and the shippingChoice, taxes are added to the amount you provided. The amounts you specified in the request and those returned in the response remain the same.

JSON
JSON
"items": [
{
"skuId": "09062016",
"amount": 30.0,
"quantity": 3,
"tax": {
"rate": 0.07525,
"amount": 2.26
}
},
{
"skuId": "11141976",
"amount": 16.0,
"quantity": 2,
"tax": {
"rate": 0.07525,
"amount": 1.2
}
}
],
"shippingChoice": {
"amount": 5.0,
"description": "USPS: Priority (1 day delivery)",
"serviceLevel": "SG",
"taxAmount": 0.38
},

The subtotal is the pre-tax cost of the items and shipping. The totalTax is determined by adding the taxes on the items and shipping. The subTotal is added to the totalTax to arrive at the totalAmount.

JSON
JSON
"totalAmount": 54.84,
"subtotal": 51.00,
"totalFees": 0.0,
"totalTax": 3.84,
"totalDuty": 0.0,
"totalDiscount": 0.0,
"totalShipping": 5.00,