# Setting the purchase location

Prior to collecting customers' [address information](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/providing-address-information), you might want to provide them with a useful tax estimate. To do this, you can define the [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/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 <API_key>' \
--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 <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"
    }    
}'
```

{% 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 <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"
    }
}'
```

{% endtab %}

{% tab title="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"
    }
}'
```

{% 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.&#x20;

{% 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 %}