Shopify Cart API Merchandise Out of Stock Error Fix

Unraveling the Shopify Cart API 'Out of Stock' Enigma

Ever scratched your head, staring at your Shopify admin, seeing a healthy stock count for a product, only to have your API calls insist it's "sold out"? It's a frustrating head-scratcher that recently popped up in the Shopify community, and it's a perfect example of how a tiny detail can derail an entire integration. Let's dive into a recent discussion that shed some much-needed light on this exact issue.

The Problem: Products in Stock, Cart API Says Otherwise

Our story starts with a developer named azar, who was testing the UCP Cart MCP endpoint for create_cart on their dev store, "northstar-outfitters-demo.myshopify.com". The goal was simple: add a product to a cart. The reality? A persistent merchandise_out_of_stock warning, even though the product clearly showed 25 units in stock and was active in the admin.

azar's initial request looked something like this:

"jsonrpc": "2.0",

"method": "tools/call",

"id": 1,

"params": {

  "name": "create_cart",

  "arguments": {

    "meta": {"ucp-agent": {"profile": "https://shopify.dev/ucp/agent-profiles/examples/2026-08-25/valid-with-capabilities.json"}},

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

  }

}

The response was a "success" but with an empty cart and that pesky warning:

"line_items": [],

"totals": [{"amount": 0}, {"amount": 0}],

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

To make things even more confusing, azar noted that a search_catalog call on the same endpoint correctly showed availability.available: true for the product. It seemed like the cart and catalog APIs were telling different stories. azar had already checked all the usual suspects: location fulfillment, shipping profiles, store policies, payment providers, and confirmed the US market was active and included the US. Nothing seemed to fix it.

The Community Steps In: Lumine's Breakthrough Discovery

This is where another community member, lumine, jumped in with some brilliant detective work. Instead of guessing, lumine systematically reproduced the issue and started testing variables. The key insight came from manipulating the cart.context block.

Here's what lumine found:

No context: `line_items: []` and `merchandise_out_of_stock` (azar's original issue).
{"address_country": "US"}: Bingo! The line item went in, and the cart populated with the correct subtotal.
{"address_country": "CA"}: Back to `merchandise_out_of_stock`.
{"address_country": "GB"}: Still `merchandise_out_of_stock`.
{"currency": "USD"} alone: `merchandise_out_of_stock`.
{"language": "en"} alone: `merchandise_out_of_stock`.

The pattern was clear: address_country was the field that made all the difference. Since azar's dev store had an active US market, only "US" as the `address_country` allowed the cart to be created successfully.

The 'Why': Markets, Context, and Misleading Errors

Lumine's explanation for *why* this happens is incredibly important for anyone working with Shopify's APIs, especially those dealing with international sales. Essentially, Shopify's cart API needs to know the buyer's country to resolve against your store's active markets. If you don't provide an address_country in the context, or if the country you provide isn't part of an active market in your store, the API can't determine pricing, taxes, or availability for that region. Instead of throwing a "market not supported" error, it defaults to the rather unhelpful merchandise_out_of_stock message.

This also explains the discrepancy with search_catalog. As lumine pointed out, the catalog API answers without the country gate – it's simply telling you if the product exists and has stock. The cart API, however, applies the market rules. They're not reading different stock levels; they're answering different questions.

The Solution: Always Provide Context!

The fix, as confirmed by azar, is straightforward: always include an address_country in your cart.context when making create_cart calls. Here's what the corrected request looks like:

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

Even if you're only selling to one country, explicitly defining it in the context is crucial for the API to function correctly.

Broader Implications for International Stores

This insight extends beyond just fixing a dev store issue. If you plan to serve countries beyond your primary one, you *must* ensure those markets are active in your Shopify admin. An agent (or an API call) reaching your store from a country you haven't set up an active market for will get told the entire catalog is "sold out," rather than a more accurate "unavailable in your region" message. This can be incredibly confusing for both developers and potential customers.

So, the big takeaway here is that when dealing with Shopify's cart API, context is everything. That seemingly innocuous address_country field isn't just a detail; it's a gatekeeper that determines whether your products are seen as available or mysteriously "sold out." Always remember to provide the necessary context, and keep your markets updated for all the regions you intend to serve to avoid these kinds of frustrating dead ends.

Mystery Solved: Why Your Shopify Cart API Says 'Out of Stock' When Products Are Available