Channels

A channel is a market: the locales its pages speak, the currency its prices are in and the countries it serves. The home store sells in one channel, de, in German and English:

{
    "channels": [
        {
            "id": "de",
            "label": { "de": "Deutschland", "en": "Germany" },
            "locales": ["de", "en"],
            "currency": "EUR",
            "countries": ["DE"]
        }
    ]
}

Labels, URLs and slugs exist per locale, prices per channel. countries guards privacy: the search log masks a phone number a shopper types into search, read as written there, before it keeps the query.

A release without channels.json derives it from the catalog: the locales its texts are keyed by or written in, the channels its offers name, and the currency their prices write. Changing channels.json rebuilds the indexes.

Reference: channels.json · locales · currency

The channel and locale a request getsCopy Anchor Link

A request without channel is answered in the first channel, and without locale in that channel's first locale. The trace says which it got:

curl -s 'http://127.0.0.1:7800/v1/search?query=sofa&debug=1' | jq -c '.trace.request | {channel, locale}'

{"channel":"de","locale":"de"}

A locale the channel does not serve is refused, and the answer names the ones it does:

curl -s 'http://127.0.0.1:7800/v1/search?query=sofa&locale=fr' | jq -r '.violations[].message'

The channel de serves de and en, not fr.

Channel, locale and context shows the same search in English.

Reference: channel · locale

Prices in the channel's currencyCopy Anchor Link

Every offer is in its channel's currency. An offer without currency takes the channel's, and a catalog line whose offer names another currency is left out and reported, since the shopper would see a wrong price.

Offer fields written on a variant, such as "price": 749.0, are its offer in the only channel. A shop with several channels gives each variant one offer per channel instead:

{ "id": "SOFA-ASKA-2-GRAU", "offers": [{ "channel": "de", "price": 749.0, "availability": "in_stock" }] }

Reference: offers · currency

What a channel sellsCopy Anchor Link

An assortment is a selector for the products a channel sells. This one leaves out the lamps by Lumivo, such as the pendant lamp LEUCHTE-KUGEL:

{
    "channels": [
        { "id": "de", "locales": ["de", "en"], "currency": "EUR", "assortment": { "not": { "brand": "Lumivo" } } }
    ]
}

The index run applies it to every variant. A variant it leaves out has no offer in the channel, so searches, facet counts, suggestions and the product page all leave it out, and no request can bring it back. The selector reads attributes, the brand and the offer fields of its own channel, never a relation.

POST $api/preview/find names the assortment when it is why a product is missing.

Reference: assortment

Context for rulesCopy Anchor Link

context declares the keys a request may carry, with the values each allows, so business customers can get rules of their own:

{
    "channels": [{ "id": "de", "locales": ["de", "en"], "currency": "EUR" }],
    "context": { "customer_group": ["b2c", "b2b"] }
}

A request then sends "context": { "customer_group": "b2b" }, and a rule's when.context matches it (Rules). A rule that names an undeclared key fails validation, and a request that sends one is refused with a 400. Context never carries personal data. The home store declares none.

Reference: context · when.context

NextCopy Anchor Link

• Search and browse: send the channel, locale and context with a request.
• Types and attributes: the labels each locale shows.
• Live prices and stock: change an offer in a channel between two catalogs.