Country specs
Learn how the CountrySpecs API can help you determine whether address and tax identifier information is required and also whether it is properly formatted.
Last updated
Learn how the CountrySpecs API can help you determine whether address and tax identifier information is required and also whether it is properly formatted.
Last updated
As the of your goods, Digital River needs specific customer data so that we can authorize payments, compute taxes, arrange fulfillments, and comply with invoicing regulations. The data required and how it is formatted depend on the combination of the and country.
The returns schemas based on the and country combination you provide. You can then use these schemas to determine whether an address component or tax identifier is required and also whether it is properly formatted.
With the CountrySpecs API, you provide Digital River with a and a country code representing the customer's expected billing and shipping address. Digital River then one or more of the following schemas:
Billing address
This schema can be used in conjunction with the ship to address schema to process orders that contain physical goods. All data fields are optional except those required to process payments.
Ship to address
This schema can be used in conjunction with the billing address schema to process orders that contain physical goods. All data fields are optional except those necessary for invoice compliance, tax computations, and shipping details.
Billing address only
This schema can be used for orders that contain only digital products since it does not validate the format of any ship to address components. All data fields are optional except those necessary for payment processing, invoice compliance, and tax computations.
Individual tax identifier
Provides validation keywords and regular expressions to determine if tax identifiers for individuals are required and properly formatted.
Business tax identifier
Provides validation keywords and regular expressions to determine if tax identifiers for businesses are required and properly formatted.
When you can provide an appropriate selling entity, the currently provides the address and tax identifier schemas for the United Kingdom, France, Germany, Italy, Spain, Canada, and the United States. Some countries, such as Poland and Brazil, only return the tax identifier schemas, while others do not have any available.
In the various address schemas, you can use the following keys to specify an address: name, organization, line1, line2, neighborhood, city, postalCode, state, and country. Each key contains .
The required validation keyword indicates which keys the customer must provide.
If a tax identifier is necessary, the required validation keyword contains a populated array. Otherwise, the array is empty.
type
Constraint on the type of the property. Possible values are string, number, integer, boolean, or array
Enumeration
Yes
integer
description
A general description of the property
String
No
VAT ID for Italy (Individual)
minLength
Constraint that defines the minimum length of the property
Integer
No
0
maxLength
Constraint that defines the maximum length of the property
Integer
No
128
pattern
Constraint expressed as a regular expression. This field is used for postal codes and tax identifiers.
String
No
^[0-9]{5}(?:-[0-9]{4})?$
enum
Constraint expressed as an enumeration. This field is used for states and countries.
Array
No
GB
When you create, update, or retrieve a Checkout, a sellingEntity is returned in the response and contains id and name values. You should use the id value to set the sellingEntity parameter when requesting a CountrySpec.
The following GET request retrieves the CountrySpec for Italy by setting the country to IT and the sellingEntity parameter to DR_IRELAND-ENTITY.
The response returns a CountrySpec that consists of a data array containing schemas formatted as strings.
If either the specified country or sellingEntity are not found, the response returns an empty data array.
The following shows the billing address schema for products ordered in Italy (IT) and sold through the Digital River Ireland Ltd. entity (DR_IRELAND-ENTITY).
The type validation keyword indicates that the billing address data will be verified as a JSON object.
The keys, such as name, organization, and line1, all contain validation keywords except for description, that act as constraints.
The minLength and maxLength validation keywords, which both require an integer, define the allowable length of the name, organization, line1, line2, and city.
The postalCode key specifies a pattern , consisting of a regular expression, that the input data must match.
For country, the enum validation keyword constrains entries to IT . Multiple enumerations are available when a schema contains the state key, as is the case for addresses in the United States.
The required validation keyword indicates which keys the customer must provide. In this example, the customer must enter a valid country and postalCode.
The following shows the business tax identifier address schema for products ordered in Italy (IT) and sold through the Digital River Ireland Ltd. entity (DR_IRELAND-ENTITY).
The type validation keyword indicates that the tax identifier data will be verified as a JSON object.
The taxIdentifier key provides a pattern keyword, consisting of a regular expression, that the input data must match.
The required validation keyword contains an empty array, indicating that no tax identifier is required for Italian businesses to place an online order. If an identifier were required, the array would contain \"taxIdentifier\".
In these schemas, the taxIdentifier key uses a the format of the tax identifier.
Other than description , which is an annotation keyword; the following validation keywords may be used as constraints to ensure that or input data is correctly formatted.
To retrieve a CountrySpec, you must provide a country code and selling entity as query parameters in a GET /country-specs request. The country parameter is an representing the customer's expected billing or ship-to address. The sellingEntity parameter represents the assigned to the order.