From aaac63b7ef52dd3812716437d2567d6432e40a43 Mon Sep 17 00:00:00 2001 From: Jared Hoover Date: Wed, 2 Sep 2026 13:55:39 -0500 Subject: [PATCH 1/2] draft --- .../graphql/schema/cart/queries/index.md | 2 + .../cart/queries/source-availability.md | 96 +++++++++++++++++++ 2 files changed, 98 insertions(+) create mode 100644 src/pages/graphql/schema/cart/queries/source-availability.md diff --git a/src/pages/graphql/schema/cart/queries/index.md b/src/pages/graphql/schema/cart/queries/index.md index 48520c281..97355ec29 100644 --- a/src/pages/graphql/schema/cart/queries/index.md +++ b/src/pages/graphql/schema/cart/queries/index.md @@ -8,3 +8,5 @@ description: The cart query returns the content of the shopper's cart. Adobe Com The [`cart`](cart.md) query returns the content of the shopper's cart. Adobe Commerce returns the [`Cart`](/reference/graphql/latest/types-c-e.md#cart) object. This object is also returned by numerous mutations, including those that add products to the cart and prepare a cart for checkout. When Inventory Management is installed and configured, you can use the [`pickupLocations`](pickup-locations.md) query to help a shopper determine whether their order can be picked up at a physical location. This query is most useful when the shopper has selected one or more items for purchase. + +Use the [`sourceAvailability`](source-availability.md) query to check per-source inventory availability for one or more SKUs before nominating a source on a cart item. diff --git a/src/pages/graphql/schema/cart/queries/source-availability.md b/src/pages/graphql/schema/cart/queries/source-availability.md new file mode 100644 index 000000000..9bc0e61ba --- /dev/null +++ b/src/pages/graphql/schema/cart/queries/source-availability.md @@ -0,0 +1,96 @@ +--- +title: sourceAvailability query +description: Use the sourceAvailability query to check per-source inventory availability for one or more SKUs, scoped to the current sales channel's assigned stock sources. +--- + + + +# sourceAvailability query + +Use the `sourceAvailability` query to check per-source inventory availability for one or more SKUs. The query reports availability only for the inventory sources assigned and enabled for the current sales channel's stock, and computes availability the same way the order-placement guard does, so a storefront read never disagrees with what checkout allows. + +A merchant admin must enable this query before it returns data. Go to **Stores** > Configuration > **Catalog** > **Inventory** > **Per-Source Availability (Storefront)** and set **Enable sourceAvailability GraphQL Query** to **Yes**. The query is disabled by default because it discloses which sources stock a SKU, and returns an error while disabled. + +Requesting a `source_codes` value that is not assigned to the current sales channel does not return an error. The unrecognized code is silently dropped from the response so its existence is never disclosed. + + + +The exact `available_qty` value is returned only when it is at or below the merchant's storefront display threshold (`cataloginventory/options/stock_threshold_qty`). Above the threshold, `available_qty` is `null` and `is_in_stock` is the only reliable signal. The threshold defaults to `0`, so by default every positive quantity is masked and `is_in_stock` is the authoritative field to check. + +## Syntax + +```graphql +sourceAvailability (skus: [String!]! source_codes: [String!] only_in_stock: Boolean): [SkuSourceAvailability!]! +``` + +| Argument | Description | +| --- | --- | +| `skus` | The product SKUs to report availability for. Required. Accepts up to 100 entries. | +| `source_codes` | Restricts the report to these inventory sources. Accepts up to 100 entries. When omitted, the query reports every source assigned to the current sales channel's stock. | +| `only_in_stock` | When `true`, omits sources where the SKU is not salable. Defaults to `false`. | + +## Reference + +The [`sourceAvailability`](/reference/graphql/saas/index.md#sourceavailability) reference provides detailed information about the types and fields defined in this query. + +## Example usage + +The following query checks availability for a single SKU at two named sources. + +**Request:** + +```graphql +{ + sourceAvailability( + skus: ["24-MB01"] + source_codes: ["default", "east-warehouse"] + only_in_stock: false + ) { + sku + sources { + source_code + sku + available_qty + is_in_stock + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "sourceAvailability": [ + { + "sku": "24-MB01", + "sources": [ + { + "source_code": "default", + "sku": "24-MB01", + "available_qty": null, + "is_in_stock": true + }, + { + "source_code": "east-warehouse", + "sku": "24-MB01", + "available_qty": 0, + "is_in_stock": false + } + ] + } + ] + } +} +``` + +## Errors + +| Error | Description | +| --- | --- | +| `Required parameter "skus" is missing or empty.` | The `skus` argument was omitted or is an empty list. | +| `Parameter "skus" may contain at most 100 entries.` | The `skus` argument contains more than 100 entries. | +| `Parameter "source_codes" must be a list of source codes.` | The `source_codes` argument was provided as a non-list value. | +| `Parameter "source_codes" may contain at most 100 entries.` | The `source_codes` argument contains more than 100 entries. | +| `The per-source availability query is not enabled for this store.` | A merchant admin has not enabled the query for the current store. | From 28a34f6292231659125c4338546fa07f60a2dc5e Mon Sep 17 00:00:00 2001 From: Jared Hoover Date: Wed, 2 Sep 2026 16:01:05 -0500 Subject: [PATCH 2/2] COMDOX-1796 GraphQL for Per source availability --- src/pages/graphql/schema/cart/queries/index.md | 2 -- src/pages/graphql/schema/products/queries/index.md | 1 + .../queries/source-availability.md | 12 ++++-------- 3 files changed, 5 insertions(+), 10 deletions(-) rename src/pages/graphql/schema/{cart => products}/queries/source-availability.md (69%) diff --git a/src/pages/graphql/schema/cart/queries/index.md b/src/pages/graphql/schema/cart/queries/index.md index 97355ec29..48520c281 100644 --- a/src/pages/graphql/schema/cart/queries/index.md +++ b/src/pages/graphql/schema/cart/queries/index.md @@ -8,5 +8,3 @@ description: The cart query returns the content of the shopper's cart. Adobe Com The [`cart`](cart.md) query returns the content of the shopper's cart. Adobe Commerce returns the [`Cart`](/reference/graphql/latest/types-c-e.md#cart) object. This object is also returned by numerous mutations, including those that add products to the cart and prepare a cart for checkout. When Inventory Management is installed and configured, you can use the [`pickupLocations`](pickup-locations.md) query to help a shopper determine whether their order can be picked up at a physical location. This query is most useful when the shopper has selected one or more items for purchase. - -Use the [`sourceAvailability`](source-availability.md) query to check per-source inventory availability for one or more SKUs before nominating a source on a cart item. diff --git a/src/pages/graphql/schema/products/queries/index.md b/src/pages/graphql/schema/products/queries/index.md index 5d642fe72..e03a1bb45 100644 --- a/src/pages/graphql/schema/products/queries/index.md +++ b/src/pages/graphql/schema/products/queries/index.md @@ -16,6 +16,7 @@ This section describes the following queries: * [`productReviewRatingsMetadata`](product-review-ratings-metadata.md) * [`products`](products.md) * [`route`](route.md) +* [`sourceAvailability`](source-availability.md) * [`urlResolver`](url-resolver.md) diff --git a/src/pages/graphql/schema/cart/queries/source-availability.md b/src/pages/graphql/schema/products/queries/source-availability.md similarity index 69% rename from src/pages/graphql/schema/cart/queries/source-availability.md rename to src/pages/graphql/schema/products/queries/source-availability.md index 9bc0e61ba..33c8cece9 100644 --- a/src/pages/graphql/schema/cart/queries/source-availability.md +++ b/src/pages/graphql/schema/products/queries/source-availability.md @@ -7,15 +7,11 @@ description: Use the sourceAvailability query to check per-source inventory avai # sourceAvailability query -Use the `sourceAvailability` query to check per-source inventory availability for one or more SKUs. The query reports availability only for the inventory sources assigned and enabled for the current sales channel's stock, and computes availability the same way the order-placement guard does, so a storefront read never disagrees with what checkout allows. +Use the `sourceAvailability` query to check per-source inventory availability for one or more SKUs. The query reports availability only for the inventory sources assigned and enabled for the current sales channel's stock, so a storefront read never disagrees with what checkout allows. -A merchant admin must enable this query before it returns data. Go to **Stores** > Configuration > **Catalog** > **Inventory** > **Per-Source Availability (Storefront)** and set **Enable sourceAvailability GraphQL Query** to **Yes**. The query is disabled by default because it discloses which sources stock a SKU, and returns an error while disabled. +An admin must enable this query before it returns data. Go to **Stores** > Configuration > **Catalog** > **Inventory** > **Per-Source Availability (Storefront)** and set **Enable `sourceAvailability` GraphQL Query** to **Yes**. The query is disabled by default because it discloses which sources stock a SKU, and returns an error while disabled. -Requesting a `source_codes` value that is not assigned to the current sales channel does not return an error. The unrecognized code is silently dropped from the response so its existence is never disclosed. - - - -The exact `available_qty` value is returned only when it is at or below the merchant's storefront display threshold (`cataloginventory/options/stock_threshold_qty`). Above the threshold, `available_qty` is `null` and `is_in_stock` is the only reliable signal. The threshold defaults to `0`, so by default every positive quantity is masked and `is_in_stock` is the authoritative field to check. +The exact `available_qty` value is returned only when it is at or below the store's **Only X left Threshold** setting. Above the threshold, `available_qty` is `null` and `is_in_stock` is the only reliable signal. This threshold defaults to `0`, so by default every positive quantity is masked and `is_in_stock` is the authoritative field to check. To change it, go to **Stores** > Configuration > **Catalog** > **Inventory** > **Stock Options** and set **Only X left Threshold**. ## Syntax @@ -93,4 +89,4 @@ The following query checks availability for a single SKU at two named sources. | `Parameter "skus" may contain at most 100 entries.` | The `skus` argument contains more than 100 entries. | | `Parameter "source_codes" must be a list of source codes.` | The `source_codes` argument was provided as a non-list value. | | `Parameter "source_codes" may contain at most 100 entries.` | The `source_codes` argument contains more than 100 entries. | -| `The per-source availability query is not enabled for this store.` | A merchant admin has not enabled the query for the current store. | +| `The per-source availability query is not enabled for this store.` | An admin has not enabled the query for the current store. |