---
title: >-
  Cart mutations now return error for invalid merchandise configuration -
  Shopify developer changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: >-
    https://shopify.dev/changelog/storefront-api-cart-now-exposes-invalid-merchandise-configuration-error
  md: >-
    https://shopify.dev/changelog/storefront-api-cart-now-exposes-invalid-merchandise-configuration-error.md
metadata:
  effectiveApiVersion: 2025-10
  affectedApi:
    - displayName: Storefront GraphQL API
      handle: storefront-graphql
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: New
    handle: new
  indicatesActionRequired: false
  createdAt: '2025-03-28T10:47:03-04:00'
  postedAt: '2025-08-29T12:00:00-04:00'
  updatedAt: '2025-08-27T14:15:09-04:00'
  effectiveAt: '2025-03-29T12:00:00-04:00'
---

August 29, 2025

Tags:

* Storefront GraphQL API
* 2025-10

# Cart mutations now return error for invalid merchandise configuration

We have enhanced error handling for cart mutations to provide clearer feedback when merchandise cannot be added to or maintained in a cart. The cart API now returns a `MERCHANDISE_NOT_APPLICABLE` error code for specific merchandise-related issues.

### When This Error Occurs

The `MERCHANDISE_NOT_APPLICABLE` error is triggered in the following scenarios:

**Inventory & Availability Issues:**

* The item is out of stock or insufficient stock is available for the requested quantity.
* The product is not published or is unavailable in the buyer's location.
* The inventory record is missing.
* The product variant does not exist.

**Pricing & Configuration Issues:**

* There is a discrepancy between expected and actual prices.
* Gift cards have zero or invalid amounts.
* Bundle products lack required components.
* The cart line item limit is exceeded.

### What This Means for Your Integration

If you receive a `MERCHANDISE_NOT_APPLICABLE` error:

* The specified merchandise cannot be added to the cart in its current configuration.
* Notify customers about the availability issue.
* Refresh product data or adjust quantities as needed.
* For bundles, ensure all required components are present.