Providing address information

Learn how to provide ship from and ship to information for products in your checkout

The Checkout resource contains attributes that allow you to set shipping addresses. Digital River then uses the values to determine the correct selling entity and process your order.

We don't perform real-time address validation. We expect you to validate the customer's address before you supply it to us.

When using a Checkout to create an Order, certain address-related parameters are required. The specific requirements depend on whether the order contains physical or digital products and whether the products are being shipped to the United States or another country.

Ship from address

The shipFrom hash table 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 is set at the checkout-level.

Ship to address

You can specify the destination of a physical product using shipTo. Digital River uses the data contained in shipTo to ensure we accurately compute taxes and comply with local invoicing regulations.

It consists of child attributes address and additionalAddressInfo. Use address to provide basic information on the shipment's destination and additionalAddressInfo to give us more detailed information.

The shipTo hash table also contains other child attributes that allow you to provide the customer's name, phone, email, and organization.

Your Checkout can inherit shipTo values from the Customer object. But this can only occur when a Customer is associated with the Checkout and the Customer has a specified address. Finally, any shipTo values specified in the checkout process will automatically override those in the associated Customer object.

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 schema define the required address parameters and provide regular expressions to validate postal code formats.

Determining address requirements

In order for Digital River to screen for fraud and compute taxes on your order, you must provide certain address-related parameters. In many cases, the CountrySpecs API can help you determine these requirements. For each supported country, it provides one or more address schemas.

Every order must have an associated payment source. And when it is created, every payment source must use the Address object to specify a billing address.

When you use a Checkout that contains one or more physical products to create an Order, you are required to provide shipFrom.address.country and shipTo.address.country values. Additionally, orders with physical goods that ship to destinations within the United States must include the city, state, and postalCode.

You are not required to provide either shipFrom or shipTo when the checkout contains only digital products.

Sample checkout with physical products

The following create Checkout request contains physical products in the items array. As a result, when submitting the request, you must specify a country in the shipTo and shipFrom addresses.

Since the shipTo address is within the United States, the city,state and postalCode are also required.

cURL
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": "476 5th Ave",
"city": "New York",
"postalCode": "10018",
"state": "NY",
"country": "US"
},
"name": "William Brown",
"phone": "555-555-5555",
"email": null@digitalriver.com
},
"shipFrom": {
"address": {
"country": "US"
}
},
"items": [
{
"skuId": "f4f06b2b-f091-41b4-b18f-5c59a7414659",
"quantity": 3,
"price": 5.99
}
]
}'

Additional address information

Use the additionalAddressInfo attribute 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
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"
}
},
...
}'

Japanese phonetics and divisions

For Japanese addresses, customers can provide their division within their organization (for example, 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
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)"

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