Summary
This guide explains upcoming changes to channel ordering via the Exclaimer Cloud API. It defines the minimum data set required on new subscriptions and relevant amendments, how validation works, example payloads, and the rollout timeline, to assist in implementation for all partners using direct and non-direct (orchestrated/marketplace) integrations with the Exclaimer Cloud API.
Select a section below to view the relevant information:
The following changes have been made:
- Several existing fields become Mandatory (e.g., CountryCode, CurrencyCode, EndUser Company Name, MailboxCount, SKU, TrialDays).
- New identity fields are introduced:
- EndUserDomain (new, mandatory)
- ResellerDomain (new, mandatory except marketplace flows)
- ResellerCompanyName (new, optional display)
- Marketplace-specific optional enrichment fields (end-user contact/address) are accepted.
- Currency correctness: supply ISO-4217 currency_code or the Exclaimer Cloud API infers it from country_code per Finance mapping; currency becomes immutable after activation.
- Enforcement approach:
- Soft enforcement: fields marked “Mandatory” are treated as optional; orders still proceed if omitted.
- Hard enforcement: the same fields become strictly required; non-compliant orders are rejected (4xx).
2nd Feb 2026: Enforcement — send the updated field set; non-compliant requests are rejected (4xx) with clear error codes/messages.
Requests must include all required data.
The following table displays the field requirements matrix.
NOTES: The Status column uses the following key:
- Mandatory - required at Create (and relevant Update)
- Optional - accepted but not required
- Mkt-Optional - optional enrichment for marketplace orders.
Currency inference (summary): USD=US; CAD=CA; AUD=AU; EUR=Euro countries (final list via Finance); GBP default otherwise. Currency is immutable after activation.
| Field | Status | Data Type | Rules/Validation (blank if none) | Channels | Notes (blank if none) |
| CountryCode | Mandatory | string | ISO-3166-1 (e.g., GB, US, AU). Maps to data centre. | All Exclaimer Cloud API integrations | |
| CurrencyCode | Mandatory | string | If provided: ISO-4217 & validated. If missing: infer from CountryCode per Finance mapping. Immutable after activation. | All Exclaimer Cloud API integrations | GBP default unless US=USD, CA=CAD, EU=EUR, AU=AUD (Finance may override). |
| EmailAddress (Owner) | Mandatory | string | Valid email of subscription owner/admin. | All Exclaimer Cloud API integrations | |
| EndUser Company Name | Mandatory | string | Legal/recognised organisation name. | All Exclaimer Cloud API integrations | |
| EndUserDomain | Mandatory (New) | string | Valid domain syntax; primary corporate domain. | All Exclaimer Cloud API integrations | New identity field. |
| MailboxCount | Mandatory | number | Integer ≥ 1. | All Exclaimer Cloud API integrations | |
| Reseller Reference | Mandatory (except marketplace) | string | Reseller/distributor internal reference/ID. | Direct & orchestrated API flows | Not required on marketplace orders. |
| ResellerDomain | Mandatory (except marketplace) | string | Valid domain syntax. | Direct & orchestrated API flows | New identity field. |
| ResellerCompanyName | Mandatory | string | Human-readable reseller display name. | All Exclaimer Cloud API integrations | Display/label only. |
| SKU | Mandatory | string | Validated against Exclaimer catalogue. | All Exclaimer Cloud API integrations | If omitted, Microsoft Pro enforced by API. |
| FirstName (End User) | Mkt-Optional (New) | string | Marketplace flows | Accepted when provided. | |
| LastName (End User) | Mkt-Optional (New) | string | Marketplace flows | Accepted when provided. | |
| Email (End User) | Mkt-Optional (New) | string | Valid email. | Marketplace flows | Accepted when provided. |
| Address Line 1/2 | Mkt-Optional (New) | string | Marketplace flows | Accepted when provided. | |
| State/Province | Mkt-Optional (New) | string | US picklists where relevant. | Marketplace flows | Accepted when provided. |
| Phone Number | Mkt-Optional (New) | string | Marketplace flows | Accepted when provided. |
Soft enforcement (from 12 Jan 2026): Fields listed as Mandatory are temporarily treated as optional — if omitted, orders still proceed and are processed normally.
Hard enforcement (from 26 Jan 2026): The same fields become strictly mandatory — non-compliant requests are rejected (4xx) with clear error codes/messages.
The following table displays the representative error codes for hard enforcement:
| Error code | Description | Example message |
| E_CURRENCY_REQUIRED | Currency is required and inference failed. | Currency is required. Could not infer from CountryCode=XX. |
| E_COUNTRY_INVALID | Invalid CountryCode. | CountryCode must be ISO-3166-1 (e.g., GB, US). |
| E_DOMAIN_INVALID | Invalid domain syntax. | EndUserDomain is invalid: contoso..com |
| E_EMAIL_INVALID | Invalid email format. | primary_contact_email must be valid. |
| E_SKU_INVALID | Unknown or de-listed SKU. | SKU not recognised: EXCL-OLD-PLAN |
| E_FIELD_IMMUTABLE(CurrencyCode) | Attempt to change currency post-activation. | Currency cannot be changed after activation. |
Create Subscription — Direct or Orchestrated via Exclaimer Cloud API:
{
"plan_sku": "EXCL-G-PRO",
"quantity": 250,
"currency_code": "GBP",
"customer_identity": {
"customer_legal_name": "Contoso Ltd",
"primary_domain": "contoso.com",
"reseller_reference": "DIST-458752",
"reseller_domain": "reseller.co.uk",
"reseller_company_name": "Acme Reseller",
"country_code": "GB",
"primary_contact_email": "itops@contoso.com",
"nfr": false,
"user_id": "DIST-12345"
},
"trial_days": 14,
"subscription_name": "Contoso Ltd - Pro",
"send_welcome_email_to_customer": false
}
Success (abridged):
{
"subscription_id": "SUB-2b1a9f84-11e3-4c7a-923e-2d6a1b5a8c9a",
"display_id": "2d6a1b5a",
"tenant_id": "TEN-7a2d...",
"status": "ActiveTrial",
"plan_sku": "EXCL-G-PRO",
"quantity": 250,
"currency_code": "GBP",
"trial_end": "2026-02-01T00:00:00Z",
"created_at": "2026-01-12T10:05:14Z"
}
Marketplace Enrichment (optional block):
{
"marketplace_contact": {
"first_name": "Alex",
"last_name": "Taylor",
"email": "alex.taylor@contoso.com",
"address_line1": "1 Example Street",
"address_line2": "Suite 500",
"state_province": "CA",
"phone": "+1-415-555-0100"
}
}
Typical validation errors (hard enforcement):
{
"error": {
"code": "E_DOMAIN_INVALID",
"message": "EndUserDomain is invalid: contoso..com"
}
}
Complete the following steps before 12 Jan 2026:
- Confirm sandbox credentials and your API environment(s).
- Implement per field matrix; include currency logic (supply or allow inference).
- Exercise sample payloads (Postman or your client).
- Verify identity fields (domains, reseller reference) persist in your reporting.
- Schedule a brief technical readiness check with Exclaimer.
No impact; enforcement applies to new subscriptions and relevant amendments.
Can you extend trials?
Default is 14 days; partners can extend via the Exclaimer Cloud API where permitted.
What if the SKU is omitted?
The Exclaimer Cloud API enforces Microsoft Pro by default.
Are Marketplace fields mandatory?
No—optional enrichment accepted when provided.
Can you change currency later?
No—currency is immutable after activation (Finance exception only).
Is ResellerCompanyName needed?
Optional (display). Provide Reseller Reference (ID) and ResellerDomain (except for marketplace orders).
- Direct integrations with the Exclaimer Cloud API.
- Non-direct (orchestrated/marketplace) integrations that submit orders to the Exclaimer Cloud API.
- The enforcement model and field requirements apply uniformly across these channels.
Your account team will coordinate your technical point of contact and timelines.
You will receive:
- This guide
- The field matrix
- Payload examples
- Timeline reminders
For technical questions or a deep dive, contact Product (Distribution & Exclaimer Cloud API): Gabriel Odey.
For support & coordination, contact your Customer Account Manager (CAM).
USD: United States (US)
CAD: Canada (CA)
AUD: Australia (AU)
EUR: Euro-adopting countries (finalised per Finance)
GBP (default): All others, unless Finance provides a specific override