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 checkout, 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 must carefully consider the sending address information sequence. Fulfilling specific address-related requirements is essential before successfully converting a checkout to an order.

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, the shipping address takes the highest priority in our tax computation process, 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

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

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 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 may result in an inaccurate tax estimate when you attach the source to the checkout.

Address requirements and validations

Every order that you create requires 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, we validate the format of postal codes and states in checkouts where products are being shipped or billed to specific countries.

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

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

However, when you convert that checkout to an order, the checkout must contain a properly formatted email. If it doesn't, the POST /orders returns a 400 Bad Request:

POST/orders response

{
    "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."
        }
    ]
}

Billing address requirements

Every order needs to contain the customer's billing address. So, before you convert a checkout to an order, its billTo must be populated.

More specifically, the checkout's 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.

400 Bad Request

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

409 Conflict

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

If a checkout contains a primary source, you can fulfill its billTo requirements by passing the customer's billing address using the primary source creation method. If you set up your integration this way, 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, you have two options to meet our billing address requirements. You can 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

Checkouts that contain physical products must meet certain shipFrom requirements.

First, they need to have a shipFrom.address.country. If you don't provide this data when building a checkout and then convert that resource to an order, a 400 Bad Request is returned.

Error

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

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 must have a name, line1, city, postalCode, and country in shipTo. 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 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 tax invoices.

In checkouts that contain physical products, if any of the following values are missing, a create or update checkout request returns a 400 Bad Request :

Ship to line1

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

Ship to country

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

Ship to city

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

Ship to state

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

Ship to postal code

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

A missing name returns a similar 400 Bad Request when you convert the checkout to an order.

Ship to name

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

Postal code and state/province validations

When products are shipped and billed to certain countries, a checkout's ship to and bill to must contain postal code and state/province data that adheres to a standardized format.

Digital River uses the same address schemas the Country Specs API returned when performing these postal codes and state/province validations.

Checkout

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

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, POST /checkouts/{id}, createDropIn() or createSource().

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:

The same error is returned if you create a source with an invalid postal code and then associate that source with the checkout.

400 Bad Request

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

States and province validations

If the checkout's ship to and/or bill to 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, Brazilian states, or Indian states) or 2-letter province code (see Canadian provinces and territories), then the following error is returned:

400 Bad Request

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

For a list of acceptable state values, refer to:

• US states 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 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 containing 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

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
        }
    ]
}'

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

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

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

When an order contains physical products, you're required to provide a customer's shipping information.

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, we enforce billTo requirements if you only apply secondary sources to a transaction.

When sequencing address information in your 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. In these 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 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	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

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": "[e-mail]",
        "additionalAddressInfo": {
            "neighborhood": "Bela Vista"
        }
    },
    ...
}'

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:

cURL

curl https://api.digtalriver.com/customers
     -u sk_test_db9682a2-b04a-4e94-8e11-35fe8ec0b324: \
     -d currency=JPY \
     -d email="[e-mail]" \
     -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]="[e-mail]" \
     -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)"

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, use the following codes as the state values for the ship-to and bill-to addresses to represent states, territories, APO/FPO military addresses, and the District of Columbia. See ISO 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, use the following codes as the state values for the ship-to and bill-to addresses to represent Brazilian states and the federal district. See ISO 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, use the following codes as the state values for the ship-to and bill-to addresses to represent Canadian provinces and territories. See 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, use the following codes as the state values for the ship-to and bill-to addresses to represent Indian states. See ISO 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