Providing address information
Learn how to provide ship from and ship to information for products in your cart.
The Cart resource contains attributes that allow you to set the shopper's billing and shipping addresses. Digital River then uses the values to determine the correct business entity and process your order.
Basic address information
The following table describes each parameter in a billingAddress
, and shippingAddress
:
Parameter | Description |
---|---|
| The name the customer prefers. |
| The customer's first name. |
| The customer's last name. |
| The company's name. |
| The first line of the address. |
| The second line of the address. |
| The third line of the address. |
| The city of the address. |
| The state, county, province, or region. |
| The country's postal code. |
| A two-letter Alpha-2 country code as described in the ISO 3166 international standard. |
| The country's name. |
| The customer's phone number. |
| The name of the county. |
| The customer's email address. |
| The phonetic spelling of the customer's first name in Katakana. |
| The phonetic spelling of the customer's last name in Katakana. |
| The name of the division within the organization within a Japanese company. |
Japanese phonetics and divisions
For Japanese addresses, customers can provide their division within their organization (for example, the sales department). Additionally, a customer 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 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.
Digital River provides the ability to enter a phonetic name for a Japanese customer and a division in the billingAddress
and shippingAddress
objects.
Phonetic names stored in the required billing address will appear on the Order Summary page.
Add phonetics and divisions
To add phonetics to your billing and shipping addresses, add the following attributes:
"phoneticFirstName": "タロ",
"phoneticLastName": "ヤマダ",
"division": "営業部"
To the following resources:
POST /shoppers/me/carts/active
– Update the billing address and shipping address in the cart.PUT /shoppers/me/carts/active/billing-address
– Update billing address independently.PUT /shoppers/me/carts/active/shipping-address
– Update shipping address independently.
After implementing phonetic names, you will see the new fields in the response under the billing or shipping address. For example:
GET /shoppers/me/carts/active/billing-address
– Get the billing address for a cart.GET /shoppers/me/carts/active/shipping-address
– Get the shipping address for a cart.Submit cart response
US states and territories
The following lists the enumerated two-letter state
values. Digital River uses these values 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.
US states
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 |
US federal district
Two-letter Abbreviation | Federal District |
---|---|
DC | District of Columbia |
US territories
Two-letter Abbreviation | Territories |
---|---|
AS | American Samoa |
GU | Guam |
MP | Northern Mariana Islands |
PR | Puerto Rico |
VI | U.S. Virgin Islands |
US APO/FPO military addresses
Two-letter Abbreviation | APO/FPO Military Addresses |
---|---|
AE | Armed Forces |
AP | Armed Forces Pacific |
AA | Armed Forces America |
Postal codes
A postal code is a series of letters, digits, or both, sometimes including spaces or punctuation, in a postal address. The postal code format varies by country. Countries throughout the world use postal codes for sorting mail. The US ZIP Code is a type of postal code.
US ZIP Code and geocode
A ZIP Code is a group of five or nine numbers added to a postal address to assist in the sorting of mail. The five-digit ZIP Code represents the US's destination post office or delivery area. The geocode consists of the last four digits of a full nine-digit ZIP Code representing a specific delivery route within that overall delivery area. Some US states use ZIP Codes and geocodes to determine taxes. This enhancement caters to states' tax calculation requirements relying on geocodes and ZIP Codes. It will greatly benefit users in states where both ZIP Codes and geocodes are crucial for accurate tax calculation.
How it works
To enable the postalCode
feature, enter the ZIP Code and geocode in the following format: "xxxxx-yyyy,"
where the first five digits represent the ZIP Code and the last four digits represent the geocode. Digital River uses this format when calculating taxes, resulting in more precise results.
A US shopper can provide just their five-digit ZIP Code without impact. However, we recommend providing the ZIP Code and geocode to ensure the correct tax calculation.
Validation for US locales
If a shopper tries to enter their ZIP Code and geocode using the wrong format, such as entering the nine digits without a dash (123456789) or with a misplaced dash (for example, 1-23456789), Digital River will throw a 409 Conflict invalid-postal-code
that shows the correct format.
Validation for non-US locales
No changes or validations are introduced for non-US locales so that this update won't disrupt or alter the behavior of users operating in non-US regions.
Last updated