A language trick for headless commerce

If you follow my quarterly unofficial release notes for D365 Commerce CSU (example link), you’ve probably found a link to my website which hosts the latest OpenAPI documentation for the 650 Commerce CSU APIs:

In a truly headless environment, you’d want some of these APIs to adapt content based on user language. For example, when a customer user clicks a language flag in a portal to change from English to German, you’d want the content to return product names or mode of delivery descriptions in German, right?

If you look into the API request definitions, you’ll find language related properties in some of the APIs. But what the Microsoft documentation doesn’t tell you is that passing an Accept-Language header actually steers the response content - That’s our hidden gem for today.

What CSU does with Accept-Language

When you add the header, CSU will return certain translated values in that language (when translations exist and are synchronized to the channel DB).

Example request with Accept-Language header:

This header sets RequestContext.Language:

It reads the Accept-Language header
Takes the first language entry
If the header is missing or null, Commerce CSU sets RequestContext.Language as per the channel’s (online store’s) default language

Example 1: Country/region names translated in shipping APIs

If you maintain country/region translations in D365 (Address setup > Country/region > Translations), CSU can return the translated short/long names when you pass Accept-Language.

API example

GET /Commerce/GetCountryRegionsForShipping

Behavior

With Accept-Language: the response returns country/region ShortName and LongName in German (if translations exist).

This is a clean way to avoid translation work in your frontend.

Example 2: Mode of delivery descriptions translated (with a gotcha)

Mode of delivery: you cannot translate the code, but you can translate the description. CSU applies those translations when Accept-Language is set.

Works for:

GET /Commerce/GetDeliveryOptions
GET /Commerce/Carts('{Retail_CartId}')/GetDeliveryOptions

Does NOT work for

GET /Commerce/OrgUnits/GetChannelDeliveryOptions

Gotcha (important): If you configure Mode of delivery translations in D365, define translations for all languages, including the default online store language. Otherwise, when the Accept-Language header is missing and CSU will fall back to the default language (which is missing a translation), CSU will pick the “first available translation record” in an unexpected language.

Example 3: Product search and Accept-Language (subtle but useful)

This is where things get interesting. CSU product search isn’t “one engine”. Different endpoints behave differently with language:

Products/Search and SearchByText do not support searching in another language than the channel default.
SearchByCriteria can search in a non-default channel language if set in the request body. Note: this language needs to be listed under languages on the online store setup in D365 ERP to make this work.
With Accept-Language on SearchByCriteria, attribute/search condition evaluation runs against the online store’s default language and the Accept-Language language (if different), while Product Name/Description are returned in the Accept-Language language.

Concrete example For a channel with default language en-us, using:

POST /Commerce/Products/SearchByCriteria
Accept-Language: de
Search condition: “Brush” (default language) or “Bürste” (Accept-Language) — both work

Result: both search conditions return the same product, with Name and Description in German — “Bürste-CB 4-reihig Kunststoffkopf 600”. Attribute values will also be translated into the Accept-Language (de) if translations exist.

Because this is the kind of thing that:

improves customer experience immediately,
reduces frontend translation complexity,
and is easy to miss if you only test with default channel language.

If you’re building headless Commerce on CSU, add Accept-Language to your test scripts and see where it changes your responses.