# Providing address information

You can use [customers ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers)and [checkouts ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)to provide [ship from](#ship-from-address), [ship to](#ship-to-address), and [bill to](#bill-to-address) address-related information. During [checkout](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/..#sequencing-the-checkout-process), we use this information to select the correct [selling entity](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/selling-entities), determine whether [tax identifiers](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/tax-identifiers#when-tax-identifiers-can-be-applied-to-orders) are applicable, [screen for fraud](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#fraud-review), and [compute taxes](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/tax-calculations).

{% hint style="warning" %}
Except in [certain scenarios](#postal-code-and-state-province-validations), we don't perform real-time address validation. Instead, we expect you to validate the customer's address before sending it to us.
{% endhint %}

When [building checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts), you must carefully consider the [sending address information sequence](#sequencing-address-information-in-checkout-workflows). Fulfilling specific [address-related requirements](#address-requirements-and-validations) is essential before successfully [converting a checkout to an order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier).

## Sequencing address information in checkouts <a href="#sequencing-address-information-in-checkout-workflows" id="sequencing-address-information-in-checkout-workflows"></a>

For [checkouts ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)that contain [physical products](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus#how-products-are-specified-as-physical-or-digital), we recommend you send a customer's [shipping address](#ship-to-address) and [billing address](#billing-address-requirements) in the [create checkout request](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1).

We suggest this sequencing because, the shipping address takes the highest priority in our tax computation process, followed by the billing address, and then, finally, the [purchase location](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/setting-the-purchase-location). If we generate a tax estimate based on the checkout's [`billTo`](#bill-to-address), and then update that estimate using a [`shipTo`](#ship-to-address) you provide in a [`POST /checkouts/{id}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1) request, you could receive the following error when you [convert the checkout to an order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier):

{% tabs %}
{% tab title="400 Bad Request" %}

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "order_submit_failed",
            "message": "Payment session status is invalid."
        }
    ]
}
```

{% endtab %}
{% endtabs %}

For transactions that contain only [digital products](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus#how-products-are-specified-as-physical-or-digital), we recommend that you first collect the customer's current billing information and use it to set the checkout's [`billTo`](#bill-to-address). In a subsequent [update checkout request](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1), you can [attach the payment source to the checkout](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts).

Since no [ship to address](#ship-to-address) is required for digital-only transactions, this sequence ensures accurate tax estimates and reduces the frequency of order failures. If you don't first send `billTo`, an outdated billing address on the [primary payment source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#primary-payment-sources) may result in an inaccurate tax estimate when you attach the source to the checkout.

## Address requirements and validations

Every [order ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)that you create [requires an email address](#email-address-requirements). We also [require the customer's billing information](#billing-address-requirements).

If a [checkout ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)only contains [digital products](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus#how-products-are-specified-as-physical-or-digital), you're *not* required to provide either [`shipFrom`](#ship-from-address) or [`shipTo`](#ship-to-address). However, when [building a checkout](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts) that contains [physical products](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus#how-products-are-specified-as-physical-or-digital), you [must set the ship from country](#ship-from-requirements) as well as [certain ship to parameters](#ship-to-requirements).

Additionally, we [validate the format of postal codes and states](#postal-code-and-state-province-validations) in [checkouts ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)where products are being shipped or billed to specific countries.

{% hint style="warning" %}
In [registered checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/using-the-checkout-identifier#registered-checkouts-or-invoices), unless you're using [version ](https://app.gitbook.com/s/ZrhMyLX5esFYS64lNWVW/digital-river-api-reference-guide/versioning)`2021-03-23` or earlier of the Digital River APIs, we do not use the associated [customer's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers)`email`, `shipping`, and [default source's](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#setting-the-default-payment-source) `owner` values to populate undefined `email`, `shipTo`, and `billTo` attributes in the [checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts).
{% endhint %}

### Email address requirements

In both `POST /checkouts` and `POST /checkouts/{id}` requests, the first-class `email` parameter is technically optional.

{% tabs %}
{% tab title="POST/checkouts request" %}

```javascript
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
...
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
    ...
    "email": "janedoe@digitalriver.com",
    "shipTo": {
        ...
    },
    "shipFrom": {
        ...
    },
    "items": [
        {
            ...
        }
    ],
    ...
}'
```

{% endtab %}
{% endtabs %}

However, when you [convert that checkout to an order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier), the checkout must contain a properly formatted `email`. If it doesn't, the `POST /orders` returns a `400 Bad Request`:

{% tabs %}
{% tab title="POST/orders response" %}

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "order_create_failed",
            "parameter": "email",
            "message": "The order could not be created because a required checkout parameter is missing. Update the checkout information provided before trying again."
        }
    ]
}
```

{% endtab %}
{% endtabs %}

### Billing address requirements

Every [order ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)needs to contain the customer's billing address. So, before you [convert a checkout to an order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier), its [`billTo`](#bill-to-address) must be populated.

More specifically, the [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`billTo` must contain `line1`, `city`, `country`, `postalCode`, and `name`. If it doesn't, you will receive either a `400 Bad Request` that identifies which parameter is missing or a `409 Conflict` that contains a more general message.

{% tabs %}
{% tab title="400 Bad Request" %}

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "missing_parameter",
            "parameter": "billTo.address.country",
            "message": "A parameter is missing."
        }
    ]
}
```

{% endtab %}

{% tab title="409 Conflict" %}

```javascript
{
    "type": "conflict",
    "errors": [
        {
            "code": "create-order-failed",
            "message": "The order is missing required details and could not be completed."
        }
    ]
}
```

{% endtab %}
{% endtabs %}

If a [checkout ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)contains a [primary source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#primary-payment-sources), you can fulfill its `billTo` requirements by passing the customer's billing address using the [primary source creation method](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#creating-primary-sources). If you set up your integration this way, we use the source's [`owner`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/digitalriver.js/payment-methods/common-payment-objects#owner-object) to set the checkout's `billTo`.

When you [combine primary and secondary sources](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#combining-primary-and-secondary-payment-sources), the billing address information associated with the primary source takes higher priority.

If you only attach [secondary sources](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#secondary-payment-sources) to a checkout, you have two options to meet our billing address requirements. You can specify `owner` in the [secondary source creation method](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#creating-secondary-sources). Or you can create the secondary source without `owner` and set the checkout's `billTo`. If you attach multiple secondary sources to a checkout, and each source contains `owner`, we use the last source attached to populate the checkout's `billTo`.

### Ship from requirements

[Checkouts](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) that contain [physical products](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus#how-products-are-specified-as-physical-or-digital) must meet certain [`shipFrom`](#ship-from-address) requirements.

First, they need to have a `shipFrom.address.country`. If you don't provide this data when [building a checkout](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts) and then [convert that resource to an order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier), a `400 Bad Request` is returned.

{% tabs %}
{% tab title="Error" %}

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "missing_parameter",
            "parameter": "shipFrom.address",
            "message": "A parameter is missing."
        }
    ]
}
```

{% endtab %}
{% endtabs %}

Second, if your goods are shipping from the United States, then some additional `shipFrom.address` requirements must be met before Digital River’s tax service calculates the taxes.

Specifically, if `country` is `US`, then:

* A `postalCode` is required and must, at a minimum, consist of five digits, all of which must be valid for a particular region or address in the United States. For example, a `postalCode` of `99999`, because it doesn't map to any actual location, won’t result in a tax calculation getting returned.
* A `state` is not required, but if you do define this parameter, then `postalCode` needs to be valid for that particular `state`. For example, if `postalCode` is `10001` and `state` is `MN`, our tax service won’t perform a calculation because the first digit of all zip codes in Minnesota is 5.

### Ship to requirements

Checkouts that contain [physical products](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus#how-products-are-specified-as-physical-or-digital) must have a `name`, `line1`, `city`, `postalCode,` and `country` in [`shipTo`](#ship-to-address). This is true for all shipping destinations. Additionally, when physical goods are being shipped to destinations within the United States or Canada, you must provide a [properly formatted](#states-and-province-validations) `state`.

{% hint style="info" %}
When the [customer type is business](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/setting-the-customer-type), you should also set the [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`shipTo.organization`. This ensures that the company's name is displayed on [tax invoices](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#tax-invoices-and-credit-memos).
{% endhint %}

In checkouts that contain [physical products](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus#how-products-are-specified-as-physical-or-digital), if any of the following values are missing, a [create ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1)or [update checkout](https://app.gitbook.com/s/ScJM6Hp95yBCPfU1nBSB/checkouts#checkouts-id-1) request returns a `400 Bad Request` :

{% tabs %}
{% tab title="Ship to line1" %}

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "missing_parameter",
            "parameter": "address.line1",
            "message": "A parameter is missing."
        }
    ]
}
```

{% endtab %}

{% tab title="Ship to country" %}

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "missing_parameter",
            "parameter": "shipTo.address.country",
            "message": "A parameter is missing."
        }
    ]
}
```

{% endtab %}

{% tab title="Ship to city" %}

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "missing_parameter",
            "parameter": "shipTo.address.city",
            "message": "A parameter is missing."
        }
    ]
}
```

{% endtab %}

{% tab title="Ship to state" %}

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "missing_parameter",
            "parameter": "shipTo.address.state",
            "message": "A parameter is missing."
        }
    ]
}
```

{% endtab %}

{% tab title="Ship to postal code" %}

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "missing_parameter",
            "parameter": "shipTo.address.postalCode",
            "message": "A parameter is missing."
        }
    ]
}
```

{% endtab %}
{% endtabs %}

A missing `name` returns a similar `400 Bad Request` when you [convert the checkout to an order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier).

{% tabs %}
{% tab title="Ship to name" %}

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "missing_parameter",
            "parameter": "shipping.name",
            "message": "A parameter is missing."
        }
    ]
}
```

{% endtab %}
{% endtabs %}

### Postal code and state/province validations

When products are shipped and billed to certain countries, a checkout's [ship to](#ship-to-requirements) and [bill to](#bill-to-address) must contain [postal code](#postal-code-validations) and [state/province](#states-and-province-validations) data that adheres to a standardized format.

{% hint style="info" %}
Digital River uses the same address schemas the [Country Specs API](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/country-specifications) returned when performing these postal codes and state/province validations.
{% endhint %}

{% code title="Checkout" %}

```javascript
{
    ...
    "shipTo": {
        "address": {
            ...
            "postalCode": "55104",
            "state": "MN",
            "country": "US"
        },
        ...
    },
    ...
    "billTo": {
        "address": {
            ...
            "postalCode": "EC1M 4AN",
            "country": "GB"
        },
        ...
    },
    ...
}
```

{% endcode %}

#### Postal code validations

Digital River validates the format of `postalCode` using a regular expression. You can use the regular expressions to validate customer-submitted postal codes on your front-end before invoking  [`POST /checkouts`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-1), [`POST /checkouts/{id}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts#checkouts-id-1), `createDropIn()` or [`createSource()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#createsource-sourcedata).

With any of these countries, an improperly formatted ship to or bill to `postalCode` in a `POST /checkouts` or `POST /checkouts/{id}` returns the following error:

{% hint style="info" %}
The same error is returned if you [create a source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#creating-payment-sources) with an invalid postal code and then [associate that source with the checkout](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts).
{% endhint %}

{% code title="400 Bad Request" %}

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "invalid_parameter",
            "parameter": "address.postalCode",
            "message": "A required address parameter, postal code, is invalid."
        }
    ]
}
```

{% endcode %}

#### States and province validations

If the checkout's [ship to](#ship-to-address) and/or [bill to](#bill-to-address) `country` is either `US` (United States of America), `BR` (Brazil), `CA` (Canada), or `IN` (India) and `state` is not a 2-letter ISO state/province code value (see [United States and territories](#us-states-and-territories), [Brazilian states](#brazilian-states), or [Indian states](#indian-states)) or 2-letter province code ([see Canadian provinces and territories](#canadian-provinces-and-territories)), then the following error is returned:&#x20;

{% code title="400 Bad Request" %}

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "invalid_parameter",
            "parameter": "address.state",
            "message": "A required address parameter, state/province, is invalid."
        }
    ]
}
```

{% endcode %}

For a list of acceptable `state` values, refer to:

* [US states and territories](#us-states-and-territories)
* [Canadian provinces and territories](#canadian-provinces-and-territories)

## Ship from address

The checkout's `shipFrom` defines the address from which a physical product is shipped. It consists of child attributes `address` and `additionalAddressInfo`. Use `address` to provide [basic information](#basic-address-information) on the shipment's origin and `additionalAddressInfo` to give us more [detailed information](#additional-address-information).

The `shipFrom` parameter can be set at either the [checkout-level](#specifying-ship-from-at-the-checkout-level) or the [item-level](#specifying-ship-from-at-the-item-level). This allows you to build an order containing items that ship from different addresses in different countries.

{% hint style="warning" %}
Your request, however, cannot contain a combination of `shipFrom` addresses that result in [more than one selling entity being assigned](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/selling-entities#determining-when-multiple-orders-are-required) to the transaction.
{% endhint %}

### Specifying ship-from at the checkout-level

The checkout-level `shipFrom` is mapped to any [line items](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/describing-the-items) that [contain a physical product](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus#how-products-are-specified-as-physical-or-digital) but don't have a `shipFrom` value.

Once the following `POST /checkouts` request is submitted, the second element in the `items` array will inherit the checkout-level `shipFrom` value.

{% tabs %}
{% tab title="cURL" %}

```
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
--data-raw '{
    ...
    "shipFrom": {
        "address": {
            "line1": "350 S 5th St",
            "city": "Minneapolis",
            "postalCode": "55415",
            "state": "MN",
            "country": "US"
        }
    },
    ...
    "items": [
        {
            "skuId": "bc4aab24-2880-4de7-b6b0-07dd6e6841a9",
            "price": 100.00,
            "quantity": 2,
            "shipFrom": {
                "address": {
                    "line1": "1800 Hiawatha Ave",
                    "city": "Minneapolis",
                    "postalCode": "55404",
                    "state": "MN",
                    "country": "US"
                }
            }
        },
        {
            "skuId": "bc4aab24-2880-4de7-b6b0-07dd6e6841a9",
            "price": 50.00,
            "quantity": 3
        }
    ]
}'
```

{% endtab %}
{% endtabs %}

If you don't set the checkout-level `shipFrom`, and one or more physical line items don't specify a `shipFrom`, you can successfully create a checkout. In this case, though, [converting the checkout to an order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier) returns the following `400 Bad Request`:

{% tabs %}
{% tab title="JSON" %}

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "missing_parameter",
            "parameter": "shipFrom.address",
            "message": "A parameter is missing."
        }
    ]
}
```

{% endtab %}
{% endtabs %}

### Specifying ship from at the item-level

By specifying `shipFrom` at the item-level, you can [build checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/..#creating-and-updating-the-checkout) containing [physical products](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus#how-products-are-specified-as-physical-or-digital) that ship from different countries. A `shipFrom` is not required at the line item-level unless no `shipFrom` is provided at the [checkout-level](#specifying-ship-from-at-the-checkout-level).

Additionally, any `shipFrom` values set at the item-level take priority over the checkout-level `shipFrom`.

## Ship to address

When an order contains [physical products](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus#how-products-are-specified-as-physical-or-digital), you're [required to provide a customer's shipping information](#ship-to-requirements).

{% hint style="warning" %}
In [registered checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/using-the-checkout-identifier#registered-checkouts-or-invoices), unless you're using version `2021-03-23` or earlier of the Digital River APIs, we do not use the associated [customer's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers) `shipping` values to populate the [checkout's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) `shipTo`.
{% endhint %}

You should use `address` to provide [basic information](#basic-address-information) on the shipment's destination and `additionalAddressInfo` to give us more [detailed information](#additional-address-information).

The `shipTo` and `shipping` hash tables also contain other child parameters that allow you to send the customer's `name`, `phone`, `email`, and `organization`.

## Bill to address

The `billTo` hash table contains child parameters `address` and `additionalAddressInfo`. You can use `address` to provide [basic information](#basic-address-information) on the customer's billing address and `additionalAddressInfo` to give us more [detailed information](#additional-address-information).

You can also use `billTo` to send non-address related information, such as the customer's `name`, `phone`, `email`, and `organization`.

In most scenarios, the `billTo` parameter is optional. However, we enforce [`billTo` requirements](#billing-address-requirements) if you only apply [secondary sources](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#secondary-payment-sources) to a transaction.

When [sequencing address information in your checkout workflows](#sequencing-address-information-in-checkout-workflows), you can use `billTo` to obtain an accurate tax calculation before attaching a payment source to the checkout. This is especially useful in transactions that only contain [digital products](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus#how-products-are-specified-as-physical-or-digital). In these transactions, [ship-to information](#ship-to-address) is typically not sent in the request. Therefore, Digital River needs `billTo` to generate a tax estimate.

Once you [create an invoice](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices#invoices-1) or [convert a checkout to an order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier), the response from the API includes `billTo`. This represents the billing address we used for tax computation purposes. Having this information allows you to know precisely what billing address information was used when calculating taxes. It also allows your integration to more easily retrieve any billing information that you might need to send in an email or other form of customer communications.

## Basic address information

An `Address` represents basic address information. The following table describes each parameter:

| Parameter    | Description                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `line1`      | The first line of the address                                                                                                                                                                                                                                                                                                                                                                               |
| `line2`      | The second line of the address.                                                                                                                                                                                                                                                                                                                                                                             |
| `postalCode` | <p>The postal code.<br><br>For United States addresses, Digital River supports ZIP+4 codes. They consist of the last four digits of a full nine-digit ZIP code. A nine-digit ZIP Code has two parts: the initial five digits of the zip code indicating the destination post office or delivery area and the last four digits representing a specific delivery route within that overall delivery area.</p> |
| `city`       | The city of the address                                                                                                                                                                                                                                                                                                                                                                                     |
| `state`      | The [state](#us-states-and-territories), county, province, or region.                                                                                                                                                                                                                                                                                                                                       |
| `country`    | A two-letter [Alpha-2 country code](https://www.iban.com/country-codes) as described in the [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) international standard.                                                                                                                                                                                                                             |

You can use the [CountrySpecs](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/country-specs) resource to retrieve [address schemas](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/country-specs#address-schemas) for many countries. These schemas define the required address parameters and provide regular expressions to validate postal code formats.

## Additional address information

Use `additionalAddressInfo` to capture any information that's not included in the basic `address`. This is especially useful for [Brazilian neighborhoods](#brazilian-neighborhoods) and [Japanese phonetics and divisions](#japanese-phonetics-and-divisions).

### Brazilian Neighborhoods

Brazilian addresses require a `neighborhood` for an order to be successfully created. The following example shows how to specify this value for an address in Brazil.&#x20;

{% tabs %}
{% tab title="cURL" %}

```
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Authorization: Bearer <API_key>' \
--header 'Content-Type: text/plain' \
--data-raw '{
    ...
    "shipTo": {
        "address": {
            "line1": "Av. Paulista, 1098, 1º andar",
            "line2": "apto. 101",
            "city": "São Paulo",
            "postalCode": "01310-000",
            "state": "SP",
            "country": "BR"
        },
        "name": "João Ribeiro",
        "phone": "98765-4321",
        "email": "jribeiro@acme.com",
        "additionalAddressInfo": {
            "neighborhood": "Bela Vista"
        }
    },
    ...
}'
```

{% endtab %}
{% endtabs %}

### Japanese phonetics and divisions

For Japanese addresses, customers can provide their division within their organization (for example, the sales department). Additionally, customers can enter their names in two scripting styles: Hiragana and Katakana. Hiragana is the traditional script, while Katakana is the phonetic spelling. Customer and courier services often want the phonetic spelling so they can correctly pronounce the customer's name when making a delivery. Katakana is also used by foreigners living in the country who don't have a Japanese name.

Use the `phoneticName` and `division` child attributes of `additionalAddressInfo` to provide this information:

{% tabs %}
{% tab title="cURL" %}

```
curl https://api.digtalriver.com/customers
     -u sk_test_db9682a2-b04a-4e94-8e11-35fe8ec0b324: \
     -d currency=JPY \
     -d email="shopxTest@digitalriver.com" \
     -d items[0][skuId]=sku_9234276173 \
     -d items[0][price]=9.29 \
     -d items[0][quantity]=2 \
     -d shipTo[name]="山田 太郎" \
     -d shipTo[phone]="03-1234-1234" \
     -d shipTo[email]="shopxTest@digitalriver.com" \
     -d shipTo[address][line1]="新宿区新宿1-1-1" \
     -d shipTo[address][line2]="新宿ビル203" \
     -d shipTo[address][city]="田原市" \
     -d shipTo[address][postalCode]="123-1234" \
     -d shipTo[address][country]="JP" \
     -d shipTo[additionalAddressInfo][phoneticName]="ヤマダ タロ" \  
     -d shipTo[additionalAddressInfo][division]="営業部" \         
     -d shipTo[amount]="5.95" \
     -d shippingChoice[name]="USPS: Priority (1 day delivery)"
```

{% endtab %}
{% endtabs %}

## State codes

State codes in addresses are essential for identifying specific regions within a country. For example, a unique two-letter code represents each state, territory, and federal district in the United States. These codes are used in shipping, billing, and other applications to ensure precise and efficient data handling. Understanding and using these standardized codes helps avoid errors, streamline processes, and facilitate communication across different systems.

### US states and territories

In [checkouts](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts), use the following codes as the `state` values for the [ship-to](#ship-to-address) and [bill-to](#bill-to-address) addresses to represent states, territories, APO/FPO military addresses, and the District of Columbia. See [ISO 3166:US](https://www.iso.org/obp/ui/#iso:code:3166:US) for more information on US state codes.

| Code | State          |
| ---- | -------------- |
| `AK` | Alaska         |
| `AL` | Alabama        |
| `AR` | Arkansas       |
| `AZ` | Arizona        |
| `CA` | California     |
| `CO` | Colorado       |
| `CT` | Connecticut    |
| `DE` | Delaware       |
| `FL` | Florida        |
| `GA` | Georgia        |
| `HI` | Hawaii         |
| `IA` | Iowa           |
| `ID` | Idaho          |
| `IL` | Illinois       |
| `IN` | Indiana        |
| `KS` | Kansas         |
| `KY` | Kentucky       |
| `LA` | Louisiana      |
| `MA` | Massachusetts  |
| `MD` | Maryland       |
| `ME` | Maine          |
| `MI` | Michigan       |
| `MN` | Minnesota      |
| `MO` | Missouri       |
| `MS` | Mississippi    |
| `MT` | Montana        |
| `NC` | North Carolina |
| `ND` | North Dakota   |
| `NE` | Nebraska       |
| `NH` | New Hampshire  |
| `NJ` | New Jersey     |
| `NM` | New Mexico     |
| `NV` | Nevada         |
| `NY` | New York       |
| `OH` | Ohio           |
| `OK` | Oklahoma       |
| `OR` | Oregon         |
| `PA` | Pennsylvania   |
| `RI` | Rhode Island   |
| `SD` | South Dakota   |
| `SC` | South Carolina |
| `TN` | Tennessee      |
| `TX` | Texas          |
| `UT` | Utah           |
| `VA` | Virginia       |
| `VT` | Vermont        |
| `WA` | Washington     |
| `WI` | Wisconsin      |
| `WV` | West Virginia  |
| `WY` | Wyoming        |

| Code | Federal District     |
| ---- | -------------------- |
| `DC` | District of Columbia |

| Code | Territory                      |
| ---- | ------------------------------ |
| `AS` | American Samoa                 |
| `FM` | Federated States Of Micronesia |
| `GU` | Guam                           |
| `MH` | Marshall Islands               |
| `MP` | Northern Mariana Islands       |
| `PR` | Puerto Rico                    |
| `PW` | Palau                          |
| `VI` | U.S. Virgin Islands            |

| Code | APO/FPO Military Addresses |
| ---- | -------------------------- |
| `AE` | Armed Forces               |
| `AP` | Armed Forces Pacific       |
| `AA` | Armed Forces America       |

### Brazilian states

In [checkouts](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts), use the following codes as the `state` values for the [ship-to](#ship-to-address) and [bill-to](#bill-to-address) addresses to represent Brazilian states and the federal district. See [ISO 3166:BR](https://www.iso.org/obp/ui/#iso:code:3166:BR) for more information on Brazilian state codes.

| Code | State               |
| ---- | ------------------- |
| AC   | Acre                |
| AL   | Alagoas             |
| AP   | Amapá               |
| AM   | Amazonas            |
| BA   | Bahia               |
| CE   | Ceará               |
| DF   | Distrito Federal    |
| ES   | Espírito Santo      |
| GO   | Goiás               |
| MA   | Maranhão            |
| MT   | Mato Grosso         |
| MS   | Mato Grosso do Sul  |
| MG   | Minas Gerais        |
| PR   | Paraná              |
| PB   | Paraíba             |
| PA   | Pará                |
| PE   | Pernambuco          |
| PI   | Piauí               |
| RN   | Rio Grande do Norte |
| RS   | Rio Grande do Sul   |
| RJ   | Rio de Janeiro      |
| RO   | Rondônia            |
| RR   | Roraima             |
| SC   | Santa Catarina      |
| SE   | Sergipe             |
| SP   | São Paulo           |
| TO   | Tocantins           |

### Canadian provinces and territories

In [checkouts](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts), use the following codes as the `state` values for the [ship-to](#ship-to-address) and [bill-to](#bill-to-address) addresses to represent Canadian provinces and territories. See [3166:CA](https://www.iso.org/obp/ui/#iso:code:3166:CA) for more information on Canadian state codes.

| Code | Province                  |
| ---- | ------------------------- |
| `AB` | Alberta                   |
| `BC` | British Columbia          |
| `MB` | Manitoba                  |
| `NB` | New Brunswick             |
| `NL` | Newfoundland and Labrador |
| `NS` | Nova Scotia               |
| `ON` | Ontario                   |
| `PE` | Prince Edward Island      |
| `QC` | Quebec                    |
| `SK` | Saskatchewan              |
|      |                           |

| Code | Territory             |
| ---- | --------------------- |
| `NT` | Northwest Territories |
| `NU` | Nunavut               |
| `YT` | Yukon                 |

### Indian states

In [checkouts](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts), use the following codes as the `state` values for the [ship-to](#ship-to-address) and [bill-to](#bill-to-address) addresses to represent Indian states. See [ISO 3166:IN](https://www.iso.org/obp/ui/#iso:code:3166:IN)  for more information on Indian state codes.

| Code | State                                    |
| ---- | ---------------------------------------- |
| `AN` | Andaman and Nicobar Islands              |
| AP   | Andhra Pradesh                           |
| AR   | Arunachal Pradesh                        |
| AS   | Assam                                    |
| BR   | Bihar                                    |
| CH   | Chandigarh                               |
| CG   | Chhattīsgarh                             |
| DH   | Dadra and Nagar Haveli and Daman and Diu |
| DL   | Delhi                                    |
| GA   | Goa                                      |
| GJ   | Gujarat                                  |
| HR   | Haryana                                  |
| HP   | Himachal Pradesh                         |
| JK   | Jammu and Kashmir                        |
| JH   | Jharkhand                                |
| KA   | Karnataka                                |
| KL   | Kerala                                   |
| LA   | Ladakh                                   |
| LD   | Lakshadweep                              |
| MP   | Madhya Pradesh                           |
| MH   | Maharashtra                              |
| MN   | Manipur                                  |
| ML   | Meghalaya                                |
| MZ   | Mizoram                                  |
| NL   | Nagaland                                 |
| OD   | Odisha                                   |
| PY   | Puducherry                               |
| PB   | Punjab                                   |
| RJ   | Rajasthan                                |
| SK   | Sikkim                                   |
| TN   | Tamil Nadu                               |
| TS   | Telangana                                |
| TR   | Tripura                                  |
| UP   | Uttar Pradesh                            |
| UK   | Uttarakhand                              |
| WB   | West Bengal                              |