Reference Data API

Read the countries and regions an address can name, and the timezones a customer can be given. Every list comes from the billing engine, so it holds exactly the values the engine accepts.

List Countries

GET /api/v1/reference/countries

Response:

{
  "countries": [
    { "code": "CA", "name": "Canada" },
    { "code": "DE", "name": "Germany" },
    { "code": "US", "name": "United States of America" }
  ]
}

Field	Description
countries[].code	Two-letter ISO 3166-1 country code. Send this as an address's country.
countries[].name	Name of the country.

The list is sorted by name and passed through as the billing engine holds it, so it can include entries that are not ordinary countries.

List a Country's Regions

GET /api/v1/reference/countries/{country_code}/states

country_code is the two-letter code from List Countries, in either case.

Response:

{
  "states": [
    { "code": "CA", "name": "California" },
    { "code": "GA", "name": "Georgia" },
    { "code": "NY", "name": "New York" }
  ]
}

Field	Description
states[].code	Code for the region, without a country prefix. Its format varies by country.
states[].name	Name of the state, province, or region.

The list is sorted by name. It is empty for a country that has no regions on file, which is not an error. The country and region lists change rarely and are cached for a day.

Store the name, not the code. Send the region's name as an address's state:

• A company address has to name a region the billing engine holds for that country.
• A customer address is free text, printed on the invoice exactly as you send it.

List Timezones

GET /api/v1/profile/timezones

Response:

[
  { "value": "Africa/Abidjan", "label": "Africa/Abidjan" },
  { "value": "America/New_York", "label": "America/New_York" },
  { "value": "UTC", "label": "UTC" }
]

Field	Description
value	IANA timezone name. Send this as a customer's timezone.
label	Name to display for the timezone.

The list is sorted by name and cached for a day. A customer timezone outside it is refused with 422.

Get the Default Timezone

GET /api/v1/profile/timezones/default

Response:

{ "timezone": "Europe/Prague" }

Field	Description
timezone	IANA timezone name a customer is given when created without one. null when it cannot be determined.

The default belongs to the billing environment your request acts on. With a session token that is the one X-Environment names, and live when you omit the header (see Choosing the Environment with a Session Token). With an API key it is the key's own environment. If a customer's billing day depends on the default, read it before you create the customer.