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:
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
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, in checkouts where products are being shipped or billed 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.
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
:
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, then you receive either a 400 Bad Request
that identifies which parameter is missing or a 409 Conflict
that contains a more general message.
If a checkout contains a primary source, then you can fulfill its billTo
requirements by passing the customer's billing address in 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, 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
Checkouts that contain physical products must met 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.
Second, if your goods are shipping from the United States, then some additional shipFrom.address
requirements have to be met before Digital River’s tax service performs a calculation.
Specifically, if country
is US
, then:
A
postalCode
is required and needs to, 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, apostalCode
of99999
, 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, thenpostalCode
needs to be valid for that particularstate
. For example, ifpostalCode
is10001
andstate
isMN
, then 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
:
A missing name
returns a similar 400 Bad Request
when you convert the checkout to an order.
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.
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.
States and province validations
If the checkout's ship to and/or bill to country
is either US
(United States of America) or CA
(Canada), and state
is not an enumerated value, then the following error is returned:
For a list of acceptable state
values, refer to:
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.
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
:
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, 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:
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.
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:
US states and territories
In checkouts, the following ship to and bill to address state
values can be used to represent American states, territories, APO/FPO military addresses, and the District of Columbia.
Canadian provinces and territories
In checkouts, the following ship to and bill to address state
values can be used to represent Canadian provinces and territories.
Last updated