How to

Use multi-market support

Learn how to use graphql arguments to target specific sales channels, markets, and languages in Geins Merchant API

Overview

Learn how to know use channelId, marketId, and languageId arguments to target specific sales channels, markets, and languages in Geins Merchant API.

These arguments are available in all GraphQL queries and mutations to help you control the context of your requests.

Goal

Find your available channels, markets, and languages
Use the parameters in your API requests to target specific contexts

Architecture at a glance

Discover available channels → Choose target channel/market/language → Use parameters in queries/mutations

APIs used

Merchant API: https://merchantapi.geins.io/graphql

Understanding the hierarchy

The multi-market system follows this structure:

Channel (e.g., "1|se")
├── Market 1 (e.g., "se") + Currency (SEK)
│   ├── Language 1 (e.g., "sv-SE")
│   └── Language 2 (e.g., "en-US")
├── Market 2 (e.g., "eu") + Currency (EUR)
│   └── Language 1 (e.g., "en-US")
└── Market 3 (e.g., "fi") + Currency (EUR)
    ├── Language 1 (e.g., "fi-FI")
    └── Language 2 (e.g., "sv-SE")

Channel: Sales channel (different storefronts/brands/way of selling)
Market: Geographic/business market with specific currency
Language: Content language for that market

The channelId parameter specifies which sales channel to use for the request. The id is built as {channelInternalId}|{channelAlias} (e.g., 1|se). You can find it by quering your channels, see example below.

marketId

string

The marketId parameter specifies which market to use for the request. Use the market id (e.g., SE|SEK, EU|EUR, FI|EUR) or alias (e.g., se, eu, fi) for this field. You can find it by querying your channels and their markets, see example below.
A note on marketId values:

The alias is often more user-friendly and stable to use in URLs. Often it is just the country code in lowercase (e.g., se for Sweden) when the market only uses one currency.
The id includes both country and currency (e.g., SE|SEK for Sweden with SEK currency) and is useful when a market has multiple currencies.

languageId

string

The languageId parameter specifies which language to use for the request. The id is the language code (e.g., sv-SE). You can find it by querying your channels and their languages, see example below.

Step-by-step

Discover available channels

First, get all available channels to understand your setup:

Try it out in the GraphQL Playground using the headers and query below.

Request example

query getChannels {
  channels {
    id
    name
    type
    url
    defaultLanguageId
    defaultMarketId
    languages {
      id
      name
      code
    }
    markets {
      id
      defaultLanguageId
      virtual
      onlyDisplayInCheckout
      groupKey
      alias
      allowedLanguages {
        id
        name
        code
      }
      country {
        name
        code
      }
      currency {
        name
        symbol
        code
        rate
      }
    }
  }
}

{
    "Accept": "application/json",
    "X-ApiKey": "{MERCHANT_API_KEY}"
}

Response example

200 OK

response.json

{
  "data": {
    "channels": [
      {
        "id": "1|se",
        "name": "store.se",
        "type": "webshop",
        "url": "https://store.example.com",
        "defaultLanguageId": "sv-SE",
        "defaultMarketId": "SE|SEK",
        "languages": [
          {
            "id": "sv-SE",
            "name": "Svenska",
            "code": "sv"
          },
          {
            "id": "en-US",
            "name": "English",
            "code": "en"
          }
        ],
        "markets": [
          {
            "id": "SE|SEK",
            "defaultLanguageId": "sv-SE",
            "virtual": false,
            "onlyDisplayInCheckout": false,
            "groupKey": "SCANDINAVIA",
            "alias": "se",
            "allowedLanguages": [
              {
                "id": "sv-SE",
                "name": "Svenska",
                "code": "sv"
              },
              {
                "id": "en-US",
                "name": "English",
                "code": "en"
              }
            ],
            "country": {
              "name": "Sweden",
              "code": "SE"
            },
            "currency": {
              "name": "Svenska Kronor",
              "code": "SEK",
              "symbol": "kr",
              "rate": 1
            }
          },
          {
            "id": "FI|EUR",
            "defaultLanguageId": "en-US",
            "virtual": false,
            "onlyDisplayInCheckout": false,
            "groupKey": "SCANDINAVIA",
            "alias": "fi",
            "allowedLanguages": [ ... ],
            "country": { ... },
            "currency": { ... }
          },
          {
            "id": "EU|EUR",
            "defaultLanguageId": "en-US",
            "virtual": true,
            "onlyDisplayInCheckout": false,
            "groupKey": "EU",
            "alias": "eu",
            "allowedLanguages": [ ... ],
            "country": { ... },
            "currency": { ... }
          }
        ]
      }
    ]
  }
}

Use parameters in queries and mutations

Once you know the available channels, markets, and languages, include the appropriate parameters in your API calls:

Note that it is the alias of the market that should be used as the marketId parameter value in queries and mutations.

Example: Get products for specific market

query products(
    $channelId: String
    $marketId: String
    $languageId: String
) {
  products(
    channelId: $channelId
    marketId: $marketId
    languageId: $languageId
  ) {
    count
    products {
        productId
        name
    }
  }
}

{
    "Accept": "application/json",
    "X-ApiKey": "{MERCHANT_API_KEY}"
}

{
  "channelId": "{CHANNEL_ID}",
  "languageId": "{LANGUAGE_ID}",
  "marketId": "{MARKET_ID}"
}

Example: Create cart for specific market

mutation getCart(
    $channelId: String
    $marketId: String
    $languageId: String
) {
  getCart(
    channelId: $channelId
    marketId: $marketId
    languageId: $languageId
  ) {
    id
  }
}

{
    "Accept": "application/json",
    "X-ApiKey": "{MERCHANT_API_KEY}"
}

{
  "channelId": "{CHANNEL_ID}",
  "languageId": "{LANGUAGE_ID}",
  "marketId": "{MARKET_ID}"
}

Default behavior

When parameters are omitted or invalid values are provided:

Missing channelId: Uses the default sales channel
Missing marketId: Uses the channel's default market
Missing languageId: Uses the market's default language, or if not set, the channel's default language
Invalid values: Falls back to defaults (no errors thrown)

What data changes between markets and languages

Market differences

Pricing: Different currencies (SEK, EUR, USD)
Product availability: Products may be restricted to specific channels/markets
Campaigns: Promotions can run on specific channels only
Tax calculations: Market-specific tax rules

Language differences

Product names and descriptions: Localized content
Category names: Translated navigation
Error messages: Localized user feedback
Content pages: Market-specific information

Related

Introduction

Use external shipping frame

Use an external shipping provider frame (e.g., nShift) to let customers select delivery options using Geins Merchant API