The Hidden Fix for Shopify UCP Cart API's "Out of Stock" Error: Market Context is Key

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 payment provider (test/bogus gateway) was activated.
• The US market was active and included the US.

Despite these diligent checks, the error persisted. Each fix, while important for a healthy store, didn't resolve the core issue with the create_cart API call. This highlights a common pitfall in API development: sometimes the problem isn't with your store's general configuration, but with the specific context provided in your API request.

The Breakthrough: The Critical Role of address_country in Cart Context

The solution came from a fellow community member, lumine, who meticulously tested the API endpoint. Lumine discovered that the missing piece of the puzzle was the address_country field within the cart.context object. Here's what their testing revealed:

• No context: line_items: [] and merchandise_out_of_stock.
• {"address_country": "US"}: Line item goes in, subtotal populates correctly.
• {"address_country": "CA"}: merchandise_out_of_stock.
• {"address_country": "GB"}: merchandise_out_of_stock.
• {"currency": "USD"} alone: merchandise_out_of_stock.
• {"language": "en"} alone: merchandise_out_of_stock.

The conclusion was clear: address_country was the field that decided whether the product was sellable. Azar's store had an active US market, and only when "address_country": "US" was provided did the cart populate successfully. For any other country, or without any country context, the API returned merchandise_out_of_stock.

The correct request, as identified by lumine and confirmed by azar, included the context block:

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

Why the Discrepancy Between search_catalog and create_cart?

This discovery also explained why search_catalog showed the product as available, while create_cart did not. Lumine insightfully pointed out that these two endpoints answer different questions:

• search_catalog: Answers whether a product is generally available in your store's catalog. It doesn't apply country-specific market gates by default.
• create_cart: Answers whether a product is available for purchase by a specific buyer from a specific region. It applies the country gates defined by your Shopify Markets.

When no address_country is provided in the cart context, the API can't resolve which market to apply, effectively treating the product as unavailable for that unspecified region. Instead of a market-specific error, Shopify's UCP API defaults to the more generic merchandise_out_of_stock warning, which can be incredibly misleading for developers.

Actionable Insights for Shopify Developers

This case study offers crucial lessons for anyone integrating with Shopify's UCP Cart APIs, especially for complex custom solutions or during a Shopify migration:

1. Always Provide address_country (and currency) in cart.context: This is the most critical takeaway. For any create_cart or related UCP Cart API calls, ensure you're explicitly defining the buyer's country and currency. This allows Shopify to correctly apply your market settings.
2. Ensure Shopify Markets are Active and Configured: The address_country you provide must correspond to an active market in your Shopify admin. If you plan to sell internationally, make sure you have markets set up for all target countries. If a market isn't active for a given country, even providing that country in the context won't work.
3. Understand "Merchandise Out of Stock" Beyond Inventory: This error code isn't always about physical stock levels. It can also indicate that a product is unavailable in the specified market due to market restrictions, pricing, or other configurations.
4. Test International Markets Thoroughly: If your store serves multiple countries, rigorously test your API integrations with different address_country values to ensure products are correctly priced and available in each region.
5. Leverage Shopify's UCP Documentation: While community forums are invaluable, always cross-reference with the official Shopify UCP documentation for the latest requirements and best practices for API context and market resolution. For those looking to build robust, scalable e-commerce solutions or start their journey on a platform that offers such powerful APIs, starting a Shopify store is an excellent choice, providing a solid foundation for complex integrations.

Conclusion

The "merchandise out of stock" error in Shopify's UCP Cart API, when products are clearly in stock, is a classic example of how a small missing piece of context can lead to significant development headaches. By understanding the critical role of address_country in the cart.context and ensuring your Shopify Markets are correctly configured, developers can avoid this common pitfall and build more reliable, international-ready e-commerce applications.

At Shopping Cart Mover, we understand the intricacies of Shopify development and migration. If you're facing complex integration challenges or planning a move to Shopify, our experts are here to ensure a smooth transition and robust setup.