Links

Configuring taxes

Learn how to configure taxes
During the checkout process, we provide you the ability to indicate whether taxes are included or not included in the product and shipping prices that you provide. This is one of the data points we use to calculate taxes.
While customers are checking out, how taxes should be displayed to them depends on the country.
You can use the checkout's taxInclusive flag to instruct us to either subtract taxes from or add taxes to the checkout's items[].price and shippingChoice.amount.
The default taxInclusive value is false.

Setting tax inclusive prices

If you want us to subtract taxes from the product and shipping prices that you provide, set the checkout's taxInclusive flag to true.
The following POST/checkouts request sets taxInclusive to true, specifies a shippingChoice.amount, and provides the line item's price.
POST/checkouts
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
...
--data-raw '{
"currency": "USD",
"taxInclusive": true,
"email": "[email protected]",
"shipTo": {
"address": {
"line1": "10380 Bren Road W",
"city": "Minnetonka",
"postalCode": "55343",
"state": "MN",
"country": "US"
},
"name": "John Doe"
},
"shipFrom": {
"address": {
"country": "US"
}
},
"shippingChoice": {
"amount": 5,
"description": "standard",
"serviceLevel": "SG"
},
"items": [
{
"skuId": "ed7b06bd-7b2e-4525-9156-cd6fcbe7fe42",
"quantity": 2,
"price": 10
}
]
}'
Once you submit this request, we compute shipping and line item taxes. We then subtract the computed values from the prices you provided in the request.
In the response, we provide an updated shippingChoice.amount and the computed shippingChoice.taxAmount. We do the same for the checkout's line items.
The checkout's subtotal is the pre-tax price of the line items and shipping. The totalTax is determined by aggregating the shipping and line item taxes.
Checkout
{
"id": "7ffe373b-b358-4c76-8210-5dc118ce77ae",
...
"totalAmount": 25.03,
"subtotal": 23.28,
"totalFees": 0.0,
"totalTax": 1.75,
"totalImporterTax": 0.0,
"totalDuty": 0.0,
"totalDiscount": 0.0,
"totalShipping": 4.68,
"items": [
{
"id": "1d99324f-6afa-4a90-808b-9d1234e2fc92",
"skuId": "ed7b06bd-7b2e-4525-9156-cd6fcbe7fe42",
"amount": 18.6,
"quantity": 2,
"tax": {
"rate": 0.07525,
"amount": 1.4
},
"importerTax": {
"amount": 0.0
},
"duties": {
"amount": 0.0
},
"fees": {
"amount": 0.0,
"taxAmount": 0.0
}
}
],
"shippingChoice": {
"amount": 4.68,
"description": "standard",
"serviceLevel": "SG",
"taxAmount": 0.35
},
...
}

Setting tax exclusive prices

If you want us to add taxes to the product and shipping prices that you provide, set the checkout's taxInclusive flag to false.
The following POST/checkouts request sets taxInclusive to false, specifies a shippingChoice.amount, and provides the line item's price.
POST/checkouts
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
...
--data-raw '{
"currency": "USD",
"taxInclusive": false,
"email": "[email protected]",
"shipTo": {
"address": {
"line1": "10380 Bren Road W",
"city": "Minnetonka",
"postalCode": "55343",
"state": "MN",
"country": "US"
},
"name": "John Doe"
},
"shipFrom": {
"address": {
"country": "US"
}
},
"shippingChoice": {
"amount": 5,
"description": "standard",
"serviceLevel": "SG"
},
"items": [
{
"skuId": "ed7b06bd-7b2e-4525-9156-cd6fcbe7fe42",
"quantity": 2,
"price": 10
}
]
}'
Once you submit this request, we compute shipping and line item taxes and return them in the shippingChoice.taxAmount and the items[].tax.amount .
Note that the shippingChoice.amount remains the same as the value sent in the request. Likewise, the line item's amount equals its aggregated price from the request.
The checkout's subtotal is the pre-tax price of the line items and shipping. The totalTax is determined by aggregating shipping and line item taxes.
Checkout
{
"id": "288ef50f-6b23-40ae-a8ad-3048b7f99ccf",
...
"totalAmount": 26.89,
"subtotal": 25.0,
"totalFees": 0.0,
"totalTax": 1.89,
"totalImporterTax": 0.0,
"totalDuty": 0.0,
"totalDiscount": 0.0,
"totalShipping": 5.0,
"items": [
{
"id": "b5125c43-dc3b-4da4-a299-d8d0734f2873",
"skuId": "ed7b06bd-7b2e-4525-9156-cd6fcbe7fe42",
"amount": 20.0,
"quantity": 2,
"tax": {
"rate": 0.07525,
"amount": 1.51
},
"importerTax": {
"amount": 0.0
},
"duties": {
"amount": 0.0
},
"fees": {
"amount": 0.0,
"taxAmount": 0.0
}
}
],
"shippingChoice": {
"amount": 5.0,
"description": "standard",
"serviceLevel": "SG",
"taxAmount": 0.38
},
...
}

Guidelines for displaying tax

The display of tax during the entire checkout experience should follow these guidelines (access required).