Shopify API Mystery: Solving 'Merchandise Out of Stock' on create_cart

Hey everyone! As a Shopify expert who spends a lot of time digging through community forums, I often come across really specific technical challenges that, once solved, can save countless hours for other store owners and developers. Recently, a thread caught my eye that perfectly illustrates one of those "aha!" moments, especially if you're working with Shopify's Universal Cart & Checkout (UCP) APIs.

The original post, from a developer named azar, was titled "Create_cart on UCP Cart MCP always returns merchandise_out_of_stock, even for products with stock." Sound familiar? It's a classic head-scratcher: you know your products are in stock, your admin says they're active, but your API call insists they're sold out. Let's dive into what happened and how the community figured it out.

The Frustration: Products in Stock, API Says "Sold Out"

Azar was testing the create_cart endpoint on their dev store, trying to add a product variant (gid://shopify/ProductVariant/47203299655852, if you're curious about the specifics) to a cart. The problem? Every single time, the API response came back with an empty line_items array and a warning message:

"messages": [{"type":"warning","code":"merchandise_out_of_stock","content":"The product 'Pampi Shoes' is already sold out."}]

What made it even more confusing was that the Shopify admin clearly showed 25 units in stock for these products, and their status was Active. To add to the mystery, azar also noted that calling search_catalog on the same endpoint correctly returned availability.available: true. So, the catalog seemed to know the product was there, but the cart API was stubbornly disagreeing.

Initial Troubleshooting Attempts (and why they didn't work)

Azar was thorough, checking all the usual suspects:

• Location fulfillment was turned on for online orders.
• Shipping profiles covered all locations.
• Store policies were filled in.
• A test payment gateway was active.
• Crucially, the US market was active and included the US.

Despite fixing these common configuration issues, the create_cart call still failed with the "out of stock" warning. It felt like chasing ghosts, which is a feeling many of us can relate to when debugging APIs!

The Breakthrough: The Missing address_country Context

This is where another community member, lumine, stepped in with some brilliant detective work. Lumine reproduced the issue and quickly narrowed down the problem to one specific field: address_country within the cart.context block of the API request.

Here’s what lumine found by testing different cart.context values:

• No context: line_items: [] and merchandise_out_of_stock (azar’s original issue).
• {"address_country": "US"}: Success! The line item went in, and the subtotal was correct.
• {"address_country": "CA"}, {"address_country": "GB"}: Still merchandise_out_of_stock.
• {"currency": "USD"} alone, {"language": "en"} alone: Also merchandise_out_of_stock.

The pattern was clear: address_country: "US" was the magic key. But why?

Understanding the "Country Gate" and Shopify Markets

Lumine explained that the create_cart API, unlike search_catalog, applies a "country gate." When you create a cart, Shopify needs to know where the buyer is located to determine which products are available to them based on your Shopify Markets setup. If there's no address_country provided in the context, or if the country provided doesn't have an active market that sells that product, the API defaults to returning merchandise_out_of_stock.

This is a critical distinction! The API isn't saying you literally have no stock; it's saying the product isn't available for purchase in the (implied or specified) region. Without any context, Shopify can't resolve a sellable catalog, so it assumes unavailability.

The Solution: Adding address_country to Your Cart Context

The fix is surprisingly straightforward once you know the root cause. You need to include an address_country field within the cart.context object of your create_cart request, making sure the country you specify has an active market in your Shopify store that sells the product.

Step-by-Step Instructions:

Here's how to adjust your create_cart request:

1. Identify the problematic request: Your original request likely looked something like this (similar to azar's):

   "cart": {
     "line_items": [{"item": {"id": "gid://shopify/ProductVariant/47203299655852"}, "quantity": 1}]
   }

   Notice the missing context block.

2. Add the context block with address_country: You'll want to include a context object within your cart object, specifying the address_country. It's also a good idea to include currency if you're dealing with multiple currencies, though address_country is the key here for availability.

   "cart": {
     "line_items": [{"item": {"id": "gid://shopify/ProductVariant/47203299655852"}, "quantity": 1}],
     "context": {"address_country": "US", "currency": "USD"}
   }

   In azar's case, adding address_country: "US" (since their US market was active) immediately resolved the issue, and the cart populated correctly.

3. Verify your Shopify Markets: Before making the API call, ensure that the address_country you're specifying (e.g., "US", "CA", "GB") corresponds to an active market in your Shopify admin that is configured to sell the products you're trying to add. If you try to add a product for a country that isn't part of an active market, you'll still get the merchandise_out_of_stock error.

Beyond Dev Stores: Real-World Implications

This insight isn't just for developers working on dev stores; it has significant implications for live stores, especially those serving international customers. As lumine pointed out, an agent (or an API request from an unsupported region) reaching your store from a country you do not have an active market for will be told the entire catalog is sold out. This can lead to a frustrating customer experience and lost sales, rather than a clear message like "unavailable in your region."

So, if you're building out custom cart functionalities or integrating with Shopify's UCP Cart MCP, remember this crucial detail. Always provide the relevant geographical context in your API requests, and ensure your Shopify Markets are properly configured for all the regions you intend to serve. It's a small detail that makes a world of difference in preventing those baffling "out of stock" errors!