Localization, Markets, and Pricing

The OpenTiendas API supports localized content (i18n) and market-specific pricing (l10n) for resources such as brands, categories, products and more.

Localization in OpenTiendas covers two related areas:

Content localization (i18n): localized text, HTML, SEO metadata, etc.
Pricing localization (l10n): prices and discounts for the corresponding commercial market.

OpenTiendas uses locales to request localized content. Each locale deterministically resolves to a single market for pricing.

Selecting locales

To request localized data, use the locales query parameter.
The parameter supports multiple values, separated by commas.

GET /api/v1/brands?locales=fr-FR,es-ES

Behavior:

If locales is not provided, the API defaults to the store’s primary locale (e.g. es-ES).
If locales is provided, the API returns exactly the requested locales.
If locales=ALL, the API returns all locales enabled for the store.

warning

If any requested locale is not supported by the store, the API returns 400 Bad Request with a descriptive error message.
Only locales configured in the store can be requested.

warning

locales=ALL is intended for export/synchronization use cases.
Avoid it in high-frequency polling, large list endpoints or latency-sensitive integrations.

Locales vs Markets

A locale selects the content language and format (and localized URLs where applicable).
A market selects the pricing context (currency and commercial price rules).

In OpenTiendas, the platform deterministically resolves exactly one market for each requested locale. Multiple locales may resolve to the same market.

Locale → Market mapping

The following table shows how locales are mapped to pricing markets in OpenTiendas:

Locale(s)	Resolved market key (used in `prices`)	Notes
`es-ES`, `ca-ES`	`market_es`	Spain
`fr-FR`, `fr-BE`	`market_fr`	France and Belgium
`de-DE`, `de-AT`	`market_de`	Germany and Austria
`it-IT`	`market_it`	Italy
`en-GB`, `en-CZ`, `en-NO`, `en-FI`, `en-IE`, `en-SK`, `en-IL`, `sv-SE`, `da-DK`, `pl-PL`, `el-GR`, `nl-NL`	`market_en`	English-based market covering multiple countries
`pt-PT`	`market_pt`	Portugal
`ru-RU`	`market_ru`	Russia

info

Market identifiers are platform-defined (e.g. market_fr) and do not need to match locale codes. Always read market keys from the API response and do not infer them from the locale.

Fixed and default fields

All resources expose a fixed set of fields and a default set of fields.

Fixed fields are always included and cannot be excluded.
They uniquely identify the resource and define its structure (for example, id).
Default fields represent the minimal, canonical representation of the resource.
They are returned when the resource is nested, and when the resource is queried without specifying the fields parameter.

This keeps responses lightweight, predictable, and consistent across endpoints.

Controlling the response shape

When querying a resource directly, you can control the response shape using:

fields — to select which fields of the current resource are returned
includes — to include related resources as nested objects

Field selection rules

All fixed fields are always returned and cannot be excluded.
When fields is not specified, the resource’s default fields are returned.
When fields is specified, the response includes only:
- all fixed fields, and
- the fields explicitly listed in fields

Default fields that are not explicitly requested are omitted.

Related objects (`includes`)

Related objects are never returned by default unless documented otherwise.
To include a related object, you must explicitly request it using includes.
Each included object is returned using its own fixed and default fields.

note

fields and includes apply to the primary resource of the endpoint being queried, whether the response returns:

a single resource (e.g. GET /api/v1/brands/{id}), or
a collection of resources (e.g. GET /api/v1/brands).

In list endpoints, the rules are applied to each item in the collection.

They do not cascade into nested or related objects.
Each related resource must be expanded independently and has its own field rules.

info

This page explains localization and pricing concepts. The API Reference documents, per endpoint, fixed fields, default fields, available fields, includes, and translatable fields.

Translatable fields and `translations`

All translatable fields appear only inside translations.
Translatable fields are never returned at the root level.

translations is a dictionary:

Keys are locale codes (e.g. es-ES)
Values are objects containing the localized fields for that locale

When you request a translatable field by name (e.g. name, meta_title), it will appear under translations.{locale} for each requested locale.

Example: Brand with localized fields

GET /api/v1/brands/2?locales=es-ES,fr-FR&fields=internal_id,name,description,meta_title,meta_description,slug

{
  "id": 2,
  "internal_id": "BRAND-001",
  "translations": {
    "es-ES": {
      "name": "Marca de ejemplo",
      "description": "Descripción en español",
      "meta_title": "Meta title ES",
      "meta_description": "Meta description ES",
      "slug": "example-brand"
    },
    "fr-FR": {
      "name": "Marque d'exemple",
      "description": "Description en français",
      "meta_title": "Meta title FR",
      "meta_description": "Meta description FR",
      "slug": "example-brand"
    }
  }
}

In this example:

id is a fixed field (always returned).
The other fields are included because they were explicitly requested via fields.

info

If you request a single locale (for example, locales=fr-FR), translations will contain a single key.

The keys present in translations correspond exactly to the locales requested via the locales parameter. For a given locale, fields may be present with empty values or null, depending on their applicability and state.

note

Translatable fields are controlled using the same fields mechanism described above; their values are always returned under translations.{locale}.

Pricing (`prices`)

Pricing is not part of translations.

For resources where pricing applies (typically variants), pricing is returned under a dedicated prices object.
prices is keyed by market identifiers (for example, market_es, market_fr).

In OpenTiendas, pricing resolution is deterministic:

each requested locale resolves to exactly one market
pricing is returned for the markets derived from the requested locales

If multiple requested locales resolve to the same market, the response will include a single prices.{market_*} entry.
As a result, you may receive fewer market entries than locales requested.

Prices are always returned in the market’s canonical currency.

If the platform displays prices in other currencies (for example, based on user preference), those values are derived from the canonical market price using currency conversion.
Currency conversion does not modify the underlying market price.

Example: Variant prices by market

{
  "id": 2001,
  "sku": "CAM-BLANCA-M",
  "prices": {
    "market_es": {
      "selling_price": { "amount": "18.00", "currency": "EUR" }
    },
    "market_fr": {
      "selling_price": { "amount": "19.00", "currency": "EUR" }
    }
  }
}

warning

Do not assume that prices uses the same keys as translations.
translations is keyed by locale, while prices is keyed by market.

Updating translations

To create or update localized fields, send them inside the translations object in your POST or PATCH payload.

Each key in translations represents a locale, and its value contains the localized fields to set for that locale.

Only provided fields are updated; others remain unchanged.

{
  "translations": {
    "en-GB": {
      "description": "New English description"
    },
    "es-ES": {
      "meta_description": "Nueva meta descripción"
    }
  }
}

Supported locales

Locale codes follow the format language-COUNTRY (for example, es-ES, fr-FR).

Supported locales are configured per store. If you request a locale that is not enabled for the store, the API returns 400 Bad Request.

es-ES — Spanish (Spain)
ca-ES — Catalan (Spain)
en-GB — English (United Kingdom)
fr-FR — French (France)
it-IT — Italian (Italy)
pt-PT — Portuguese (Portugal)
de-DE — German (Germany)
ru-RU — Russian (Russia)
nl-NL — Dutch (Netherlands)
sv-SE — Swedish (Sweden)
da-DK — Danish (Denmark)
pl-PL — Polish (Poland)
el-GR — Greek (Greece)

warning

Locales outside this list (for example, es-AR, en-AU) are not currently supported and will result in a 400 Bad Request.

Common translatable fields

Common translatable fields (depending on the resource) include:

name
description
body_html
long_name
meta_title
meta_description
slug
slug_base
url

For the full list of translatable fields per resource, refer to the API Reference.

Selecting locales​

Locales vs Markets​

Locale → Market mapping​

Fixed and default fields​

Controlling the response shape​

Field selection rules​

Related objects (includes)​

Translatable fields and translations​

Example: Brand with localized fields​

Pricing (prices)​

Example: Variant prices by market​

Updating translations​

Supported locales​

Common translatable fields​

Selecting locales

Locales vs Markets

Locale → Market mapping

Fixed and default fields

Controlling the response shape

Field selection rules

Related objects (`includes`)

Translatable fields and `translations`

Example: Brand with localized fields

Pricing (`prices`)

Example: Variant prices by market

Updating translations

Supported locales

Common translatable fields