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:

Parameter	Optional/Required	Description.
country	Required	An 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

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:

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
        }
    ]
}'

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 a purchaseLocation is provided, Digital River returns a tax estimate at both the line item and checkout level:

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"
    },
...
}

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"
    },
...
}

Use case: Storefronts with mostly domestic customers

Your company is located in Italy and the vast majority of your storefront customers are Italians. By having country in purchaseLocation default to IT, you can give your customers an initial tax estimate that's applicable 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. On your storefront, you might want to implement a text field that collects a US-based customer's zip code and then displays estimated taxes for the products in their cart. In the following two POST /checkouts requests, country is defined as US but different postalCode values are provided:

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, depending on the postalCode input, different items[].tax.rate values have been applied, resulting in different totalTax and items[].tax.amount values.

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"
    },
...
}