Setting the purchase location
Learn how to get a tax estimate during checkouts before you have a customer's address information
Prior to collecting customers' address information, you might want to provide them with a useful tax estimate. To do this, you can define the checkout's purchaseLocation
.
The object contains the following three parameters:
state
Optional
The state, county, province, or region
postalCode
Optional (except for purchase locations in the United States)
ZIP or postal code
Using purchase location to get a tax estimate
If you don't yet have a customer's shipping or billing address, purchaseLocation
can be used to generate a tax estimate. The following shows two POST /checkouts
requests, with and without a purchaseLocation
:
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
}
]
}'
When a purchaseLocation
is provided, Digital River returns a tax estimate at both the line item and checkout level:
{
"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"
},
...
}
Use case: Storefronts with mostly domestic customers
Your company is located in Italy, and most of your storefront customers are Italians. By having country
in purchaseLocation
default to IT
, you can give your customers an initial tax estimate that applies to most of them.
Use case: Different postal codes in the United States
In the United States, tax rates can differ by postal code region. You might want to implement a text field on your storefront that collects a US-based customer's zip code and then displays estimated product taxes in their cart.
In the following two POST /checkouts
requests, country
is defined as US
but different postalCode
values are provided:
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Authorization: Bearer <API_key>' \
--header 'Content-Type: text/plain' \
--data-raw '{
"currency": "USD",
"items":
[
{
"skuId": "09062016",
"price": 10.00
},
{
"skuId": "11141976",
"price": 10.00
}
],
"purchaseLocation":
{
"country": "US",
"postalCode": "95969"
}
}'
The responses show how depending on the postalCode
input, different items[].tax.rate
values have been applied, resulting in different totalTax
and items[].tax.amount
values.
{
...
"totalAmount": 21.56,
"subtotal": 20.0,
"totalFees": 0.0,
"totalTax": 1.56,
"totalDuty": 0.0,
"totalDiscount": 0.0,
"totalShipping": 0.0,
"items": [
{
"skuId": "09062016",
"amount": 10.0,
"quantity": 1,
"tax": {
"rate": 0.0775,
"amount": 0.78
}
},
{
"skuId": "11141976",
"amount": 10.0,
"quantity": 1,
"tax": {
"rate": 0.0775,
"amount": 0.78
}
}
],
"locale": "en_US",
"purchaseLocation": {
"country": "US",
"postalCode": "95969"
},
...
}
Last updated