Providing address information
Learn how to provide billing, shipping and email address-related information.
You can use customers and checkouts to provide ship from, ship to, and bill to address-related information. During the checkout process, we use this information to select the correct selling entity, determine whether tax identifiers are applicable, screen for fraud, and compute taxes.
Except in certain scenarios, we don't perform real-time address validation. Instead, we expect you to validate the customer's address before sending it to us.
When building checkouts, you should pay close attention to how you sequence sending address information. And before you can successfully convert a checkout to an order, you must meet certain address-related requirements.

Sequencing address information in checkouts

For checkouts that contain physical products, we recommend you send a customer's shipping address and billing address in the create checkout request.
We suggest this sequencing because, in our tax computation process, the shipping address takes highest priority, followed by the billing address, and then, finally, the purchase location. If we generate a tax estimate based on the checkout's billTo, and then update that estimate using a shipTo you provide in a POST/checkouts/{id} request, you could receive the following error when you convert the checkout to an order:
400 Bad Request
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "order_submit_failed",
6
"message": "Payment session status is invalid."
7
}
8
]
9
}
Copied!
For transactions that contain only digital products, we recommend that you first collect the customer's current billing information and use it to set the checkout's billTo. In a subsequent update checkout request, you can attach the payment source to the checkout.
Since no ship to address is required on digital-only transactions, this sequence ensures tax estimates are accurate and reduces the frequency of order failures. If you don't first send billTo, an outdated billing address on the primary payment source may result in an inaccurate tax estimate when you attach the source to the checkout.

Address requirements and validations

For every order that you submit, we require an email address. We also require the customer's billing information.
If a checkout only contains digital products, you're not required to provide either shipFrom or shipTo. However, when building a checkout that contains physical products, you must set the ship from country as well as certain ship to parameters.
Additionally, in checkouts where products are being shipped to specific countries, we validate the format of postal codes and states.
In registered checkouts, unless you're using version 2021-03-23 or earlier of the Digital River APIs, we do not use the associated customer's email, shipping, and default source's owner values to populate undefined email, shipTo, and billTo attributes in the checkout.

Email address requirements

In both POST/checkouts and POST/checkouts/{id} requests, the first-class email parameter is technically optional.
POST/checkouts request
1
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
2
...
3
--header 'Authorization: Bearer <API_key>' \
4
...
5
--data-raw '{
6
...
7
"email": "[email protected]",
8
"shipTo": {
9
...
10
},
11
"shipFrom": {
12
...
13
},
14
"items": [
15
{
16
...
17
}
18
],
19
...
20
}'
Copied!
However, when you convert that checkout to an order, the checkout must contain a properly formatted email. If it doesn't, the POST/orders request returns a 400 Bad Request:
POST/orders response
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "order_create_failed",
6
"parameter": "email",
7
"message": "The order could not be created because a required checkout parameter is missing. Update the checkout information provided before trying again."
8
}
9
]
10
}
Copied!

Billing address requirements

Every order must contain the customer's billing address. So, before you convert a checkout to an order, verify that the checkout's billTo exists.
More specifically, billTo must contain line1, city, country, postalCode, and name. If it doesn't, then you receive either a 400 Bad Request that identifies which parameter is missing or a 409 Conflict that contains a more general message.
400 Bad Request
409 Conflict
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "missing_parameter",
6
"parameter": "billTo.address.country",
7
"message": "A parameter is missing."
8
}
9
]
10
}
Copied!
1
{
2
"type": "conflict",
3
"errors": [
4
{
5
"code": "create-order-failed",
6
"message": "The order is missing required details and could not be completed."
7
}
8
]
9
}
Copied!
If a checkout contains a primary source, then billTo is automatically added. This is because both primary source creation methods require billing address information, and we use the source's owner to set the checkout's billTo.
When you combine primary and secondary sources, the billing address information associated with the primary source takes higher priority.
If you only attach secondary sources to a checkout, then you have two options to meet our billing address requirements. You can either specify owner in the secondary source creation method. 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

In checkouts that contain physical products, you're required to specify a shipFrom.address.country. If you fail to provide a ship from country when building a checkout, and then convert that checkout to an order, you receive a 400 Bad Request.
POST/orders response
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "missing_parameter",
6
"parameter": "shipFrom.address",
7
"message": "A parameter is missing."
8
}
9
]
10
}
Copied!

Ship to requirements

Checkouts that contain physical products must contain a ship to name, line1, city, postalCode, and country. 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 ship to state.
When the customer type is business, you should also set the checkout's shipTo.organization. This ensures that the company's name is displayed on generated tax invoices.
In checkouts that contain physical products, when any of the following values are missing, a create or update checkout request returns a 400 Bad Request :
Ship to line1
Ship to country
Ship to city
Ship to state
Ship to postal code
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "missing_parameter",
6
"parameter": "address.line1",
7
"message": "A parameter is missing."
8
}
9
]
10
}
Copied!
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "missing_parameter",
6
"parameter": "shipTo.address.country",
7
"message": "A parameter is missing."
8
}
9
]
10
}
Copied!
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "missing_parameter",
6
"parameter": "shipTo.address.city",
7
"message": "A parameter is missing."
8
}
9
]
10
}
Copied!
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "missing_parameter",
6
"parameter": "shipTo.address.state",
7
"message": "A parameter is missing."
8
}
9
]
10
}
Copied!
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "missing_parameter",
6
"parameter": "shipTo.address.postalCode",
7
"message": "A parameter is missing."
8
}
9
]
10
}
Copied!
A missing ship to name returns a similar 400 Bad Request when you convert the checkout to an order.
Ship to name
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "missing_parameter",
6
"parameter": "shipping.name",
7
"message": "A parameter is missing."
8
}
9
]
10
}
Copied!

Postal code and state/province validations

For American, Canadian, German, French, and British address, the ship to and bill to postalCode must be properly formatted.
The same is true for US states and Canadian provinces. If an order is being shipped to the US or Canada, then the state value must adhere to a standard format.
We validate postal code and state/province formats using the same address schemas as those returned by the Country Specs API.
For these countries, when your request contains improperly formatted postal code or state/province values, we return a 400 Bad Request.
Invalid postal codes
Invalid states/provinces
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "invalid_parameter",
6
"parameter": "address.postalCode",
7
"message": "A required address parameter, postal code, is invalid."
8
}
9
]
10
}
Copied!
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "invalid_parameter",
6
"parameter": "address.state",
7
"message": "A required address parameter, state/province, is invalid."
8
}
9
]
10
}
Copied!

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 on the shipment's origin and additionalAddressInfo to give us more detailed information.
The shipFrom parameter can be set at either the checkout-level or the item-level. This allows you to build an order with items that ship from different addresses in different countries.
Your request however cannot contain a combination of shipFrom addresses that result in more than one selling entity being assigned to the transaction.

Specifying ship from at the checkout-level

The checkout-level shipFrom is mapped to any line items that contain a physical product 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.
cURL
1
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
2
--header 'Content-Type: application/json' \
3
--header 'Authorization: Bearer <API_key>' \
4
--data-raw '{
5
...
6
"shipFrom": {
7
"address": {
8
"line1": "350 S 5th St",
9
"city": "Minneapolis",
10
"postalCode": "55415",
11
"state": "MN",
12
"country": "US"
13
}
14
},
15
...
16
"items": [
17
{
18
"skuId": "bc4aab24-2880-4de7-b6b0-07dd6e6841a9",
19
"price": 100.00,
20
"quantity": 2,
21
"shipFrom": {
22
"address": {
23
"line1": "1800 Hiawatha Ave",
24
"city": "Minneapolis",
25
"postalCode": "55404",
26
"state": "MN",
27
"country": "US"
28
}
29
}
30
},
31
{
32
"skuId": "bc4aab24-2880-4de7-b6b0-07dd6e6841a9",
33
"price": 50.00,
34
"quantity": 3
35
}
36
]
37
}'
Copied!
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 returns the following 400 Bad Request:
JSON
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "missing_parameter",
6
"parameter": "shipFrom.address",
7
"message": "A parameter is missing."
8
}
9
]
10
}
Copied!

Specifying ship from at the item-level

By specifying shipFrom at the item-level, you can build checkouts containing physical products that ship from different countries. A shipFrom is not required at the line item-level unless no shipFrom is provided at the checkout-level.
Additionally, any shipFrom values set at the item-level take priority over the checkout-level shipFrom.

Ship to address

In registered checkouts, unless you're using version 2021-03-23 or earlier of the Digital River APIs, we do not use the associated customer's shipping values to populate the checkout's shipTo.
You should use address to provide basic information on the shipment's destination and additionalAddressInfo to give us more detailed 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 on the customer's billing address and additionalAddressInfo to give us more detailed 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, if you only apply secondary sources to a transaction, then we do enforce billTo requirements.
When sequencing address information in your checkout workflows, you can use billTo to obtain an accurate tax calculation prior to attaching a payment source to the checkout. This is especially useful in transactions that only contain digital products. In these types of transactions, ship to information is typically not sent in the request. Therefore, Digital River needs billTo to generate a tax estimate.
Once you create an invoice or convert a checkout to an order, the response from the API includes billTo. This represents the billing address we used for tax computation purposes. Having this information allows you to precisely know 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 provides a description of each parameter:
Parameter
Description
line1
The first line of the address
line2
The second line of the address.
postalCode
The postal code. 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.
city
The city of the address
state
The state, county, province, or region.
country
A two-letter Alpha-2 country code as described in the ISO 3166 international standard.
You can use the CountrySpecs resource to retrieve 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 and 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.
cURL
1
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
2
--header 'Authorization: Bearer <API_key>' \
3
--header 'Content-Type: text/plain' \
4
--data-raw '{
5
...
6
"shipTo": {
7
"address": {
8
"line1": "Av. Paulista, 1098, 1º andar",
9
"line2": "apto. 101",
10
"city": "São Paulo",
11
"postalCode": "01310-000",
12
"state": "SP",
13
"country": "BR"
14
},
15
"name": "João Ribeiro",
16
"phone": "98765-4321",
17
"email": "[email protected]",
18
"additionalAddressInfo": {
19
"neighborhood": "Bela Vista"
20
}
21
},
22
...
23
}'
Copied!

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 name 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:
cURL
1
curl https://api.digtalriver.com/customers
2
-u sk_test_db9682a2-b04a-4e94-8e11-35fe8ec0b324: \
3
-d currency=JPY \
4
-d email="[email protected]" \
5
-d items[0][skuId]=sku_9234276173 \
6
-d items[0][price]=9.29 \
7
-d items[0][quantity]=2 \
8
-d shipTo[name]="山田 太郎" \
9
-d shipTo[phone]="03-1234-1234" \
10
-d shipTo[email]="[email protected]" \
11
-d shipTo[address][line1]="新宿区新宿1-1-1" \
12
-d shipTo[address][line2]="新宿ビル203" \
13
-d shipTo[address][city]="田原市" \
14
-d shipTo[address][postalCode]="123-1234" \
15
-d shipTo[address][country]="JP" \
16
-d shipTo[additionalAddressInfo][phoneticName]="ヤマダ タロ" \
17
-d shipTo[additionalAddressInfo][division]="営業部" \
18
-d shipTo[amount]="5.95" \
19
-d shippingChoice[name]="USPS: Priority (1 day delivery)"
Copied!

US states and territories

The following lists the enumerated two-letter state values that Digital River uses to represent states, territories, APO/FPO military addresses, and the District of Columbia. When you specify one of these state enumerations in a request, you must also provide US as the country parameter.
Two-letter Abbreviation
State Name
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
SC
South Carolina
TN
Tennessee
TX
Texas
UT
Utah
VT
Vermont
WA
Washington
WV
West Virginia
WY
Wyoming
Two-letter Abbreviation
Federal District
DC
District of Columbia
Two-letter Abbreviation
Territories
AS
American Samoa
GU
Guam
MP
Northern Mariana Islands
PR
Puerto Rico
VI
U.S. Virgin Islands
Two-letter Abbreviation
APO/FPO Military Addresses
AE
Armed Forces
AP
Armed Forces Pacific
AA
Armed Forces America
Last modified 1mo ago