Shopper Session

Last updated October 21st at 12:46pm

Introduction#

Shoppers’ interaction with the DTC API catalog relies on a session details containing an information about pricelist, market, country, currency, and language. All this information affects the catalog content available to a shopper. Let’s explore how each of them is determined.

Session query

query session {
  session {
    country {
      code
      name
      isEU
    }
    countryState {
      code
      name
    }
    language {
      code
      name
      default
    }
    market {
      id
      name
    }
    pricelist {
      id
      name
      currency {
        code
      }
    }
    loggedIn
  }
}

Country#

Country is a formative part of a session and catalog content. DTC API detects it based on a shopper’s location. There are two flows for this:

FE calls API directly: DTC API detects the shopper's IP address. No additional actions are required.
Backend client calls DTC API: The shopper's IP address must be passed as the X-Forwarded-For header.

For countries with states, they are also detected and assigned to the session. If it’s not possible to determine the country for some reason, the default one is assigned to the session. This default country can be configured per DTC API client.

Anytime a shopper can change the country and state, use the setCountryState mutation for that purpose. Once a country is changed, DTC API determines a new market and pricelist. This action can cause some selection lines to become unavailable, having them removed with a notification in userErrors.

Market#

Each market has a list of countries assigned to it, creating a direct dependency between the selection market and country. Any country change means the market needs to be reconsidered. However, it’s possible to have some countries not assigned to any market, and for them, DTC API tries to set a store default market. In case there is no default market for the store, any available store market is assigned to the session.

Pricelist#

Each pricelist, similar to markets, has a list of countries assigned to it. Any country change triggers an revision of the pricelist. If a country is not assigned to any pricelist, DTC API tries to select it by shipping groups. That means if there is a shipping group for a session country, the pricelist where that shipping is set as a default one is set on the session. If none of those options is able to determine a pricelist, any available store pricelist is assigned to the session.

Session currency is defined by the selected pricelist and cannot be updated without a pricelist change.

Language#

Each language, similar to markets and pricelists, has a list of countries assigned to it. Once a country is set on the session, DTC API checks if there is a specific language for that country. If it’s defined, the language is set on the session; if not, English is set as a session language.

Language is not updated on country change; once it was selected, it remains the same until the shopper decides to change it. To change the language, use the setLanguage mutation provided by DTC API.

Registered customer#

On the shopper login action, the initial session state remains. That means it’s not possible to set a custom country or language on a logged-in session and login from a different device keeping custom session settings.

Catalog impact#

Now that we have information on how each of those essential session components is determined, let’s discover how they affect the catalog content available for a specific shopper.

Name	Change impact
Country	Market update, Pricelist update
Market	Product availability, Product stock, Applied campaigns
Pricelist	Product availability, Price specifications, Currency
Language	Catalog translations, Checkout widgets translations

Any Display Item can be available for all markets, as well as only for some of them. That means a country change can cause Display Items to disappear from a catalog. Also, the session market has an effect on Display Item stock, causing any Display Item to be available for some markets and not available for others. Though they are still returned in an API, it’s not possible to add them to the selection.

Display Item prices are defined per pricelist and market, where any pricelist price can be discounted by market campaigns. That means any country change can also change Display Item prices, updating currency or discounts.

Translations in Centra are defined per language, making Display Item, category, or any other type with translations able to contain different values for different languages. As a result, when language is changed on the session, it can cause Display Item to have updated names, descriptions, or any other translatable field. In case there are no translations for a specific language, the default value for a field is used.

No session mode#

The described behaviour is valid for session mode, where the session exists and all these components are detected by shopper location. For no session mode, all of them can be provided as query parameters, for example in the displayItems query, to apply the same catalog changes.