> For the complete documentation index, see [llms.txt](https://the-wishlist-documentation.gitbook.io/the-wishlist-documentation-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://the-wishlist-documentation.gitbook.io/the-wishlist-documentation-docs/shopify-general/shopify-markets.md).

# Shopify Markets

This guide explains how to configure Shopify Markets so that wishlist, back-in-stock and price-drop behaviour follows your warehouses and markets.

### Before you begin

Almost everything described here is configured in your Shopify admin. We read your delivery profiles and markets and apply those settings. Changes made in Shopify are normally reflected in our platform within four hours.

This guide applies to stores using Shopify's **Shipping Profiles** model. Shopify is moving merchants to **Shipping Options by Market**, where shipping is configured per market.  

*If Shopify shows an upgrade or migration notice for your store, please contact us before proceeding so we can confirm compatibility.*

### What you configure, and where

| What                                                            | Where                                                              |
| --------------------------------------------------------------- | ------------------------------------------------------------------ |
| Which warehouses serve which countries, per product             | Shopify: **Settings > Shipping and delivery > Delivery profiles**  |
| Which countries belong to each market, and their market prices  | Shopify: **Settings > Markets**                                    |
| API access to read this information                             | Shopify app permissions (re-consent may be required)               |
| Enabling Markets behaviour for your store                       | Contact us                                                         |
| Exclude a warehouse from a single market's stock                | Shopify: Settings > Shipping and delivery > Delivery profiles zone |
| Excluding a warehouse from stock counts site-wide (all markets) | We can configure this for you.  Contact us.                        |
| Setting the minimum stock quantity for notifications            | Managed in your notifications settings in back-office              |

### Step 1: Allocate warehouses to countries in delivery profiles

This is the most important step. We determine which warehouses can serve a customer from your delivery profiles.

Delivery profiles apply per product. Each profile covers a set of products and variants, so eligibility is calculated for each product rather than for your store as a whole. For example, fragile or oversized items in a separate profile may have different warehouse eligibility from other products.

In each delivery profile, a **location group** contains one or more warehouses, and each **zone** lists the countries that group ships to. For a product assigned to a profile:

* A country listed in a zone is served by the warehouses in that location group.
* If a country appears in zones belonging to two location groups, it is served by both and their stock is combined.
* If a country appears in none of the profile's zones, no warehouse is considered able to serve it and customers there will not be notified about that product.

A three-warehouse setup might look like this:

| Location group | Zone covers                     |
| -------------- | ------------------------------- |
| US warehouse   | United States and Canada        |
| UK warehouse   | United Kingdom and EU countries |
| AU warehouse   | Australia and Rest of World     |

### Step 2: Make Rest of World an explicit zone

If you want to serve customers outside your named countries, add an explicit **Rest of World** zone to the relevant delivery profile. Leaving countries out of every zone is not the same: customers in those countries will not receive notifications.

With a Rest of World zone, any country not named explicitly in that profile is served by the warehouses assigned to that zone. If a country is named explicitly, its named zone takes precedence over Rest of World.

If the same country is deliberately served by two location groups—one explicitly and one through Rest of World—contact us so we can confirm how the configuration will be interpreted.

### Step 3: Grant the required API permissions

We require three Shopify API scopes:

* `read_shipping` to read your delivery profiles and determine which warehouses serve each country
* `read_markets` to read your markets
* `read_products` to read your catalogues and market price lists

Granting a new scope requires you to re-consent to the app. If Markets behaviour appears inactive, check these permissions first. If a required scope is missing, Markets processing is skipped for your store.

### Step 4: Confirm inventory reaches us by location

Inventory must include the Shopify location it belongs to. Without the location, we cannot determine which warehouse holds the stock, so it will not count towards any market.

We use the stock figure supplied for each location. If you use negative inventory or allow purchasing when an item is out of stock, contact us so we can confirm how those settings interact with your notification thresholds.

### How we determine a customer's country

Country is used for two purposes: deciding which warehouses can serve a customer and determining which market price applies.

#### Stock notifications and wishlist reminders

At send time, we use the best available destination country in this order:

1. The country held directly on the customer record in our platform, where supplied by your systems
2. The country on the customer's default address
3. The country captured when the wishlist item was saved, if supplied by your storefront

We use the shipping destination rather than the country where the customer happened to be browsing because the destination determines which warehouses can serve them.

* **Eligibility is resolved at send time.** Wishlist items are not permanently tied to a warehouse. Existing items follow changes to your delivery configuration.
* **If a customer moves**, they are assessed against the new destination after the updated country reaches our customer record.
* **If no country is available**, we cannot determine a destination and will not send the notification.

#### Price-drop notifications

Price drops are detected within each market by comparing its current price with the last price recorded for the same market. We do not compare prices across markets or currencies, or against the price captured when an item was first saved.

A customer is notified only when the price falls in the market that applies to their destination country. For example, if a customer browses your UK store but ships to Australia, the Australian price applies. If their country changes, future assessments use the new market; comparisons are never carried across markets.

We also suppress a price-drop notification when a country moves between markets because the price change resulted from reassignment rather than a discount.

### How inventory is counted

#### Stock is combined across eligible warehouses

If the UK is served by both your UK and AU warehouses, a UK customer is assessed against the combined stock of both. Two units in AU and none in the UK still count as available because the AU warehouse is configured to serve the UK.

The same rule applies to the minimum stock quantity. A threshold of three for the UK means three units in total across all warehouses serving the UK, not three units in the UK warehouse alone.

#### To make a market use one warehouse only

Remove the other warehouse from that country's zone in the relevant delivery profile. If the UK zone lists only the UK warehouse, UK customers are assessed against UK stock alone.

#### Minimum stock quantity is a single value

One default threshold applies to your store. Per-market and per-warehouse thresholds are not currently supported.

#### There is no warehouse priority

We determine whether stock exists in any warehouse configured to ship to the customer's country. We do not model a preferred or nearest warehouse, so a rule such as “notify on UK stock and use AU only as a fallback” cannot currently be represented.

#### Notifications do not identify the warehouse

A customer notified because stock is available in a secondary warehouse is not told where the item will ship from. Consider whether this could create different delivery expectations.

#### We do not validate the complete checkout path

We confirm that an eligible warehouse holds enough stock. We do not also confirm that the market is active, that the product is published in that market's catalogue, or that a delivery rate exists for the destination.

In a standard configuration, these settings should align. If you deactivate a market, unpublish a product from a market catalogue, or leave a zone without a delivery rate, a customer could be notified about a product they cannot purchase.

### Submarkets and overlapping markets

Shopify allows a country to belong to more than one market. A Canada market inside a wider North America market is a common example. For pricing, we give the more specific market precedence: when one market's countries are entirely contained within another's, the smaller market supplies the price.

Shopify does not directly identify the parent market to us, so we infer the relationship. This works for straightforward nested markets. If two markets overlap but neither is entirely contained within the other, contact us so we can confirm which market and price will apply.

### Current limitations

| Limitation                                      | What it means                                                                                                                                                                          |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Shopify Shipping Options by Market              | We currently read the Shipping Profiles model. Our current approach remains compatible, but you may receive a warning from Shopify when configuring.  Contact us for more information. |
| B2B, POS and channel markets                    | We read regional markets defined by countries. Markets defined by company location, retail location or sales channel are not included.                                                 |
| States, provinces and other sub-country regions | Allocation is by country. A market or delivery zone defined only by state or province cannot be represented.                                                                           |
| Per-warehouse or per-market stock thresholds    | One threshold applies wherever the product is sold.                                                                                                                                    |
| Preferred or nearest warehouse                  | Stock is combined across eligible warehouses; warehouse priority is not supported.                                                                                                     |
| Market catalogue and delivery-rate validation   | We check shipping configuration and stock, but not the complete checkout path.                                                                                                         |

### Worked examples

These examples use the three-warehouse setup above: the US warehouse serves the United States and Canada, the UK warehouse serves the United Kingdom and EU, and the AU warehouse serves Australia and Rest of World.

| Scenario                                                                                               | What happens                                                                                                                     | Why                                                                                       |
| ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Five units arrive at the UK warehouse after an item was out of stock everywhere.                       | UK and EU customers are notified. US, Canadian and Australian customers are not.                                                 | The UK warehouse serves only the UK and EU.                                               |
| The AU warehouse holds 50 units and three units arrive at the UK warehouse.                            | UK and EU customers are notified.                                                                                                | AU stock was not available to them; their eligible stock changed from zero to three.      |
| The AU warehouse is also added to the UK zone, and all stock is in Australia.                          | UK customers are treated as having stock available.                                                                              | Stock is combined across every warehouse configured to serve the country.                 |
| The UK threshold is three, with one unit in the UK and two in Australia; both warehouses serve the UK. | The threshold is met.                                                                                                            | Three units are available across eligible warehouses.                                     |
| Stock arrives at the AU warehouse, which has Australia and Rest of World zones.                        | Australian customers and customers in unnamed countries, such as Japan, may be notified.                                         | Both zones are served by the AU warehouse.                                                |
| A US customer is waiting when the AU warehouse restocks.                                               | The US customer is not notified.                                                                                                 | The US is explicitly served by the US warehouse, so Rest of World does not apply.         |
| There is no Rest of World zone and a customer in Japan is waiting.                                     | The Japanese customer is not notified.                                                                                           | Japan is in no zone, so no warehouse is eligible to serve it.                             |
| A customer browses the UK store but their destination is Australia. The Australian price falls.        | They are notified about the Australian price drop.                                                                               | Destination country determines the applicable market price.                               |
| Canada belongs to North America and Canada-only markets with separate price lists.                     | Canadian customers receive the Canada market price.                                                                              | Canada-only is the more specific market.                                                  |
| A fragile product is in a profile that ships only within Australia.                                    | Only Australian customers are notified about that product.                                                                       | Eligibility comes from the product's delivery profile.                                    |
| The UK moves from the AU warehouse to a new UK warehouse.                                              | UK customers use UK stock after the next refresh. A qualifying notification may be missed while the new baseline is established. | Changing the warehouse group requires a new notification baseline. Contact us beforehand. |

### Which notifications follow your markets

| Notification                | Behaviour                                                                                                  |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Notify me (back in stock)   | Triggered per region and sent only to customers whose destination can be served by the region's warehouses |
| Wishlist item back in stock | Triggered per region using that region's eligible stock                                                    |
| Low stock                   | Triggered per region using that region's eligible stock                                                    |
| Price drop                  | Detected within a market and sent only to customers in that market                                         |
| Wishlist reminders          | Rechecked at send time against eligible warehouse stock                                                    |

### How quickly changes take effect

We refresh delivery profiles and market price lists every four hours. Changes made in Shopify are normally reflected within four hours, provided Shopify API access and scheduled synchronisation are operating normally. Contact us if you need an immediate refresh.

Price changes in your home market are normally received immediately through Shopify notifications.

### Troubleshooting a notification

We can check a product variant and destination country to identify:

* Which warehouses can serve the destination
* How much stock each warehouse holds
* Which stock is included in the decision
* The applicable market price
* The final notification decision and reason

If a customer reports that a notification was not sent, contact us with the product variant and destination country. Missing delivery zones and missing API permissions are common causes.

### Adding a new warehouse

The order matters because stock in a warehouse does not count until it is assigned to an applicable zone.

1. **Create the location in Shopify** and enable it for fulfilment.
2. **Add it to each relevant delivery profile.** Place it in a location group and define the countries it will serve.
3. **Decide whether it replaces or supplements another warehouse.** Warehouses in the same zone both serve its countries and their stock is combined. Remove the old warehouse if the new one replaces it.
4. **Confirm your inventory feed** supplies stock for the new location.
5. **Contact us** so we can refresh the configuration and prepare a new notification baseline.
6. **Verify the setup** with a product expected to be available in the new region.

When decommissioning a warehouse, remove it from its zones before retiring the Shopify location.

### Before changing your delivery profiles

Please contact us before re-zoning a market or adding or removing a warehouse. Changing which warehouses serve a country changes the way inventory is grouped for notifications and requires a new starting baseline.

The baseline process is designed to prevent duplicate notifications, although one qualifying notification may be missed while the new baseline is established. Advance notice allows us to prepare for the change and verify the result.