Setting the purchase location

Learn how to set a purchase location

The optional PurchaseLocation object can be added to a Checkout to create a useful tax estimate for the customer. The data contained in the object, along with the values of other attributes, allows Digital River to estimate taxes on an order.

Use PurchaseLocation 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.

The object consists of the following attributes:

Attribute

Optional/Required

Description.

country

Required

The ISO 3166-1 alpha-2 country code

state

Optional

The state, county, province, or region.

postalCode

Optional (except for purchase locations in the United States)

ZIP or postal code

Example: Storefronts with mostly domestic customers

Your company is located in Italy and the vast majority of your storefront customers are Italians. By specifying the country attribute of the purchaseLocation hash in a create Checkout request, you can give them an initial tax estimate before they provide their ship to or billing address.

Example: Different postalCode values in the United States

For purchase locations in the United States, you need to provide a postalCode. The following POST checkout requests specify different postalCode values for the purchaseLocation hash:

Postal Code: 95969
Postal Code: 55343
Postal Code: 95969
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"
}
}'
Postal Code: 55343
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": "55343"
}
}'

The responses show how the initial tax estimate provided to the customer is affected by the postalCode because different tax.rate values are used to compute taxes :

Postal Code: 95969
Postal Code: 55343
Postal Code: 95969
{
...
"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"
},
...
}
Postal Code: 55343
{
...
"totalAmount": 21.5,
"subtotal": 20.0,
"totalFees": 0.0,
"totalTax": 1.5,
"totalDuty": 0.0,
"totalDiscount": 0.0,
"totalShipping": 0.0,
"items": [
{
"skuId": "09062016",
"amount": 10.0,
"quantity": 1,
"tax": {
"rate": 0.07525,
"amount": 0.75
}
},
{
"skuId": "11141976",
"amount": 10.0,
"quantity": 1,
"tax": {
"rate": 0.07525,
"amount": 0.75
}
}
],
"locale": "en_US",
"purchaseLocation": {
"country": "US",
"postalCode": "55343"
},
...
}