Markets

The market object and the allowed CRUD operations on the related resource endpoint

A market is made of a merchant, an inventory model, and a price list. Optionally, a market can be associated with different price list schedulers, a customer group, a geocoder, and a tax calculator.

You can define a custom alphanumeric (not case-sensitive) code for your markets, provided that it's unique across the environment (it can contain underscore and hyphens, spaces are not allowed, the maximum length is 25 characters).

Sales channels must specify a market scope when obtaining an access token. This way, all the resources (e.g., SKUs, prices, stock items) are automatically filtered.

Scheduling price changes for a market

To be able to associate a price list scheduler with a market, their price lists must share the same currency_code and tax_included attributes. The price list associated with an active price list scheduler temporarily overrides the one originally associated with the market, letting you change a subset of prices within a specific time window (e.g. seasonal sales). A market can be associated with more than one price list scheduler but, at a given moment in time, only one will be chosen to override the market's original price list.

Disabling markets

Markets are automatically enabled at the time of creation, but they can be disabled by sending a PATCH request with the _disable trigger attribute set to true. Similarly, you can use the _enable trigger attribute to re-enable a disabled market. Once a market is disabled it is excluded from any authorization scope recalculation: existing access tokens previously created with that market in scope receive a 422 Unprocessable Entity error on market-specific actions (e.g. if you try to create/update an order or a line item), any attempts to request a new access token with that market in scope receive a 400 Bad Request error (due to invalid scope).

Your plan limits refer to active (i.e. enabled) markets only. If you've reached your plan's limit in terms of the number of markets, make sure to disable one of the active markets before enabling a new one.

External URLs

When setting up a market, you can decide to manage some market-specific features using an external/custom service. Specifically:

• Prices — fill in the external_prices_url field with your external service endpoint and follow the external prices guide for more information on how to inject the unit amount price of a specific line item from an external source.

• Order validation — fill in the external_order_validation_url field with your external service endpoint and follow the external order validation guide for more information on how to trigger the validation of a specific order from an external source.

When activating both of the features above, a shared secret is generated at the market level. You can use it to verify the related callback authenticity.

Data model

Check the related ER diagram and explore the flowchart that illustrates how the market resource relates to the other API entities.