Input Formats
Clearvo normalises incoming country, currency and region values server-side before validation runs, so you can send what your billing system or platform already produces. This page says what is accepted, what is definitive, and what to do when a value does not resolve.
Countries
The country field on any address accepts, in this order of matching:
- A 2-letter code (ISO 3166-1 alpha-2), upper-cased:
"de"becomes"DE". - A 3-letter code (ISO 3166-1 alpha-3), mapped to its alpha-2 code:
"DEU"becomes"DE". All 249 official codes are covered. - An English country name, case-insensitive, including common informal names (about 190 names are recognised).
Everything is resolved to alpha-2 before validation. A few examples:
"DEU" → "DE" ISO alpha-3"GBR" → "GB" Apple StoreKit storefront"United States" → "US" English name"Holland" → "NL" informal name"Czech Republic" / "Czechia" → "CZ" both namesA name Clearvo does not recognise is passed through unchanged and the request is rejected with a validation error on that field. See custom rules to map it.
Currencies
The currency and taxReportingCurrency fields accept:
- A 3-letter ISO 4217 code, any case:
"eur"becomes"EUR". This is the definitive format; every ISO 4217 code is accepted as a code. - A currency name from a built-in list of common names (about 90, such as
"Euro","US Dollar","Pound Sterling","Japanese Yen"). - A few unambiguous symbols. Shared symbols such as
$,£,¥andkrare deliberately not guessed, because each belongs to several currencies.
"euros" → "EUR""US Dollar" / "Dollar" → "USD""British Pound" → "GBP""Canadian Dollar" → "CAD"A name outside the built-in list is left unchanged and rejected as an invalid currency. Send the ISO code, or add a custom rule.
Regions (US states and Canadian provinces)
The region field accepts the standard 1 to 3 letter code (upper-cased), or the full name of any US state, the District of Columbia, or any Canadian province or territory. That list is complete for the United States and Canada. Names in other countries are not translated.
"California" → "CA" Google Play buyerState"Washington DC" → "DC""Québec" / "Quebec" → "QC" accents optional"British Columbia" → "BC"Anything else: normalise with custom rules
The built-in lists cover the common cases. If your system sends a value that does not resolve, such as an internal country code, a legacy currency label or a region spelled your own way, you do not need to change your data. Add a normalise rule in the rules engine: it rewrites the field before validation, scoped to your organisation or a single business profile, and every change is visible in the calculation's rules trace.
- Rules change the format of a value, never its meaning, and never overwrite a value that already resolved.
- Create them in the dashboard under Rules, or through the API and MCP rules endpoints.
See Rules for the rule types and scoping.
B2B override
By default, Clearvo infers B2B treatment from a valid customer.taxId — no additional flag is needed for standard B2B checkouts. For cases where you know the buyer is a business but don't have their VAT number at checkout time, set customer.b2bOverride: true.
| Scenario | What to send |
|---|---|
| B2C consumer sale | Omit taxId and b2bOverride — B2C treatment is the default |
| B2B sale, VAT number known | Supply customer.taxId — Clearvo verifies it and applies reverse charge or zero-rating automatically |
| B2B sale, VAT number not available | Set customer.b2bOverride: true — skips VAT number validation and applies full B2B treatment for the buyer's location |
Platform integration examples
These patterns work without any field transformation on your side.
// Google Play Orders API returns buyerCountry (alpha-2) + buyerState (full name)
{
"currency": "USD",
"customer": {
"billingAddress": {
"country": "US",
"region": "California"
}
},
"lineItems": [{ "id": "1", "amount": 9.99, "productName": "App subscription" }]
}
// no taxId/b2bOverride → B2C treatment (the default); "California" → "CA" resolved before validation
// Apple StoreKit 2 returns storefront as ISO 3166-1 alpha-3
{
"currency": "USD",
"customer": {
"billingAddress": { "country": "GBR" }
},
"lineItems": [{ "id": "1", "amount": 4.99, "productName": "In-app purchase" }]
}
// "GBR" → "GB" — UK VAT (20%) applied