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 and stores, a customer group, a geocoder, and a tax calculator.
You can define a custom alphanumeric (case-sensitive) code for your markets, provided that it's unique across the environment (it can contain underscores and hyphens, spaces are not allowed, the maximum length is 25 characters).
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 (that you can still fetch by checking the base_price_list relationship).
Payment settings
A market's payment providers are configured through payment settings.
Payment settings are defined at the organization level and associated with a market via payment setting IDs.
The list of payment settings available for a specific order is exposed via the available_payment_settings relationship on the order, which returns the market's payment settings minus those gated by payment setting rules whose conditions the order doesn't meet.
Default shipping method
You can create a specific shipping method and set it as the default shipping method for one or more markets by leveraging the default_shipping_method relationship. This way all the shipments that belong to the market's orders and that are not already associated with a shipping method will be automatically associated with the default one.
To be eligible for being set as default, a shipping method must not already be associated with any of the following:
Markets
Stock locations
Shipping categories
Shipping zones
Otherwise, the API will return an error when associating the relationship.
Market-specific shipping costs policy
Based on the selected inventory strategy, an order can be associated with more than one shipment. Each shipment must be associated with a shipping method, the cost of which will result in a line item of type shipments in the order summary.
If you want to override this behavior for one or more of your markets, you can set the shipping_cost_cutoff attribute (not enabled by default). Its value defines the maximum number of shipping line items on the order that will have a cost — the remaining ones will have their unit amount set to 0. For example, setting shipping_cost_cutoff to 1 means only the shipping method first associated with an order's shipment will have a cost. The cost of any subsequent ones will be zeroed. This lets you charge the customer a single shipping cost for the whole order, for instance.
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_urlfield 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_urlfield 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.
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), while any attempts to request a new access token with that market in scope receive a 400 Bad Request error (due to invalid scope).
Last updated