> For the complete documentation index, see [llms.txt](https://docs.digitalriver.com/digital-river-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/setting-the-purchase-location.md). # Setting the purchase location Prior to collecting customers' [address information](/digital-river-api/integration-options/checkouts/creating-checkouts/providing-address-information.md), you might want to provide them with a useful tax estimate. To do this, you can define the [checkout's ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts)`purchaseLocation`. The object contains the following three parameters: | Parameter | Optional/Required | Description. | | ------------ | ------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `country` | Required | An [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/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`: {% tabs %} {% tab title="No purchaseLocation provided " %} ``` curl --location --request POST 'https://api.digitalriver.com/checkouts' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: text/plain' \ --data-raw '{ "currency": "USD", "items": [ { "skuId": "05081978", "price": 100.00, "quantity": 1 } ] }' ``` {% endtab %} {% tab title="purchaseLocation provided" %} ``` curl --location --request POST 'https://api.digitalriver.com/checkouts' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: text/plain' \ --data-raw '{ "currency": "USD", "items": [ { "skuId": "05081978", "price": 100.00, "quantity": 1 } ], "purchaseLocation": { "country": "US", "state": "MN", "postalCode": "55116" } }' ``` {% endtab %} {% endtabs %} When a `purchaseLocation` is provided, Digital River returns a tax estimate at both the line item and checkout level: {% tabs %} {% tab title="No purchaseLocation provided" %} ```javascript { "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" }, ... } ``` {% endtab %} {% tab title="purchaseLocation provided" %} ```javascript { "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" }, ... } ``` {% endtab %} {% endtabs %} ### 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: {% tabs %} {% tab title="Postal Code: 95969" %} ``` curl --location --request POST 'https://api.digitalriver.com/checkouts' \ --header 'Authorization: Bearer ' \ --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" } }' ``` {% endtab %} {% tab title="Postal Code: 55343" %} ``` curl --location --request POST 'https://api.digitalriver.com/checkouts' \ --header 'Authorization: Bearer ' \ --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" } }' ``` {% endtab %} {% endtabs %} 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. {% tabs %} {% tab title="Postal Code: 95969" %} ```javascript { ... "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" }, ... } ``` {% endtab %} {% tab title="Postal Code: 55343" %} ```javascript { ... "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" }, ... } ``` {% endtab %} {% endtabs %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/setting-the-purchase-location.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.