--- schema_version: "1" id: ce593e1db2013a168d1be67c7199721a21e20b994347443225d169c2ca7eaa6d title: Shopper Availability collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-availability.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-availability source_site: developer.salesforce.com content_type: documentation content_hash: 4de4007a24c258b048d452994de16a1c21f2fe957b30da5494956ed6ca5822d7 products: - B2C Commerce API - Salesforce APIs --- Shopper Availability # Shopper Availability [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-availability/shopper-availability-oas-v1-public.yaml) ## API Overview Use the Shopper Availability API enables to retrieve inventory availability for products without fetching full product details. This allows independent caching strategies for volatile availability data and stable product data. Use `/availability` to retrieve availability for products. If the `inventoryIds` parameter is omitted, availability is returned from the site-assigned default inventory list. If `inventoryIds` is provided, availability is returned only from the specified inventory lists. Caching is provided for the Shopper Availability API. For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html) ### Authentication & Authorization The client requesting the availability information must have access to the Availability resource. The Shopper Availability API requires a shopper access token from the Shopper Login and API Access Service (SLAS). You must include the relevant scopes in the client ID used to generate the SLAS token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html) For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html#guest-user) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html#guest-user) in the SLAS guides. ### Use Cases #### Retrieve Product Availability Use the Shopper Availability API so that a customer can see whether products are in stock. This API returns availability details, including stock levels and inventory status, for up to 24 products per request. #### Retrieve Availability from Specific Inventory Lists Use the `inventoryIds` parameter to retrieve availability from specific inventory lists rather than the site-assigned default. This is useful for scenarios such as showing availability at specific store locations or warehouses. You can request availability from up to 5 inventory lists per request. #### Retrieve Availability for Product Variations Use the `expand=variations` parameter to retrieve availability for all variants of a master product in a single request. Use the `productId` from each entry in the Shopper Products API `variants` array to look up availability for a specific variant. ### Use Hooks For details working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html) **Version:** 1.4.2 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/product/shopper-availability/v1` * `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)` ## Security * `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both the Open Commerce API (OCAPI) and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token. * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token) * Scope sfcc.shopper-availability: scope granting read-access to shopper availability endpoints * Scope sfcc.shopper-standard: standard aggregated scope granting read-access to a curated set of shopper endpoints * OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token) * Scope sfcc.shopper-availability: scope granting read-access to shopper availability endpoints * Scope sfcc.shopper-standard: standard aggregated scope granting read-access to a curated set of shopper endpoints * `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only. * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context) * Scope sfcc.shopper-availability: scope granting read-access to shopper availability endpoints * Scope sfcc.shopper-standard: standard aggregated scope granting read-access to a curated set of shopper endpoints ## Operations ### GET Returns availability for multiple products. `GET /organizations/{organizationId}/availability` Operation ID: `getAvailability`. Security: ShopperToken (sfcc.shopper-availability, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-availability, sfcc.shopper-standard). Returns availability for multiple products. If `inventoryIds` is omitted, availability is returned from the site-assigned default inventory list. If `inventoryIds` is provided, availability is returned only from the specified inventory lists. The maximum number of product IDs that you can request is 24. The maximum number of inventory list IDs you can request is 5. The `productIds` parameter accepts product IDs for any product type (master, variant, standard, set, or bundle). Products that are offline or not found are silently filtered from the response. To retrieve availability for all variants of a master product, use the `expand=variations` parameter. Use the `productId` from each entry in the Shopper Products API `variants` array to look up availability for a specific variant. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `productIds` (query, array of object, required, style: form, explode: false) The IDs of the requested products (comma-separated, max 24 IDs). If more than 24 IDs are required, split them into multiple parallel requests. Products that are offline or not found are silently filtered from the response. Minimum items: 1. Maximum items: 24. _Example_ ``` apple-ipod-shuffle,apple-ipod-nano ``` _Example_ ``` [ "apple-ipod-shuffle", "apple-ipod-nano" ] ``` * `inventoryIds` (query, array of object, style: form, explode: false) The inventory list IDs for which the availability should be shown (comma-separated, max 5 inventory list IDs). If omitted, availability is returned from the site-assigned default inventory list. If provided, availability is returned only from the specified inventory lists. Minimum items: 1. Maximum items: 5. _Example_ ``` Site1InventoryList,Site2InventoryList ``` _Example_ ``` [ "Site1InventoryList", "Site2InventoryList" ] ``` * `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites. _Example: SiteId_ ``` RefArch ``` * `expand` (query, array of string, style: form, explode: false) Expand the response to include availability for related products. When `variations` is specified, availability for all variation products of a master product is included. When `set_products` is specified, availability for all products in a product set is included. The parent product's availability is always included alongside the expanded entries. Expansion is single-level only: if a variation is itself a product set, its set products are not further expanded. Other product types (bundles, bundled items, set items) are not expanded. Expanded results are returned flat at the top level of the response array, not nested below their parent product. **Note:** When using `expand=variations`, combine this response with variant data from the Shopper Products API to determine which specific variant attribute combinations (e.g. size=L, color=red) are orderable. Use the `productId` from each entry in the Shopper Products API `variants` array as the key to look up availability for that variant in this response. Items: Allowed values: `variations`, `set_products`. Example: `variations`. _Example_ ``` variations,set_products ``` _Example_ ``` [ "variations", "set_products" ] ``` * `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken. Example: `550e8400-e29b-41d4-a716-446655440000`. * `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response. Allowed values: `none`. Example: `none`. * `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application. #### Responses * **200** Success. Media type: `application/json`. Schema: `AvailabilityResult`. _Example: GetAvailabilityResponseExample_ ``` { "data": [ { "id": "poodle-collar", "inventories": [ { "ats": 100, "backorderable": false, "id": "site-default-inventory", "inStockDate": "2026-06-15T00:00:00.0Z", "orderable": true, "preorderable": false, "stockLevel": 90 } ] }, { "id": "poodle-coat", "inventories": [ { "id": "site-default-inventory" } ] } ], "limit": 2, "total": 2 } ``` _Example: GetAvailabilityInventoryListsResponseExample_ ``` { "data": [ { "id": "poodle-collar", "inventories": [ { "ats": 100, "backorderable": false, "id": "inventory1", "orderable": true, "preorderable": false, "stockLevel": 90 }, { "ats": 5, "backorderable": false, "id": "inventory2", "orderable": true, "preorderable": true, "stockLevel": 5 } ] }, { "id": "poodle-coat", "inventories": [ { "ats": 7100, "backorderable": false, "id": "inventory1", "orderable": true, "preorderable": false, "stockLevel": 7090 }, { "ats": 15, "backorderable": false, "id": "inventory2", "orderable": true, "preorderable": true, "stockLevel": 15 } ] } ], "limit": 2, "total": 2 } ``` * **400** Bad Request Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: GetAvailabilityBadRequestResponseExample_ ``` { "title": "Bad Request", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation", "detail": "Maximum number of product IDs you can request in one call is 24." } ``` _Example: GetAvailabilityInventoryListsBadRequestResponseExample_ ``` { "title": "Bad Request", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation", "detail": "Maximum number of inventory list IDs you can request in one call is 5." } ``` _Example: MalformedSelectorResponseExample_ ``` { "title": "Malformed Selector", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-selector", "detail": "The property selector '(data.(id, inventories.(**))' is malformed.", "selector": "(data.(id, inventories.(**))" } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` #### Extension points * `sfcc.product.shopper-availability.v1.availability.beforeGET` (before) called before retrieving product availability. * `sfcc.product.shopper-availability.v1.availability.modifyGETResponse` (modifyResponse) called to modify the product availability response. ## Schemas ### OrganizationId An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). Type: `string`. Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`. ### ProductId The id (SKU) of the product. Type: `string`. Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`. ### InventoryId The inventory ID. Type: `string`. Minimum length: 1. Maximum length: 256. Example: `Site1InventoryList`. ### SiteId The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites Type: `string`. Minimum length: 1. Maximum length: 32. Example: `RefArch`. ### AvailabilityResult Result document containing an array of product availability. * `limit` (_integer (int32)_, required) The number of returned product entries in the data array. Example: `2`. * `data` (_array of Availability_, required) The array of product availability entries. Each entry represents one product (SKU) with available inventory across the requested inventory lists. * `total` (_integer (int32)_, required) The total number of distinct product entries in the data array, not individual inventory records. Example: `2`. ### ErrorResponse * `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization Maximum length: 256. Example: `You do not have enough credit`. * `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `NotEnoughMoney`. * `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem. Example: `Your current balance is 30, but that costs 50`. * `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `/account/12345/msgs/abc`. ### Availability Availability of one product across the requested inventory lists, or the site-assigned default inventory list. * `id` (_ProductId_, required) * `inventories` (_array of Inventory_, required) The array of inventory information for the product. ### Inventory Document representing inventory information of the current product for a particular inventory list. * `ats` (_number (double)_) The Available To Sell (ATS) of the product. If it is infinity, the return value is 999999. The value can be overwritten by the OCAPI setting 'product.inventory.ats.max\_threshold'. Example: `15`. * `backorderable` (_boolean_) A flag indicating whether the product is backorderable. Example: `true`. * `id` (_InventoryId_, required) * `inStockDate` (_string (date-time)_) A flag indicating the date when the product will be in stock. Example: `9999-12-31T00:00:00.0Z`. * `orderable` (_boolean_) A flag indicating whether at least one of the products is available to sell. Example: `true`. * `preorderable` (_boolean_) A flag indicating whether the product is preorderable. Example: `false`. * `stockLevel` (_number (double)_) The stock level of the product. If it is infinity, the return value is 999999. The value can be overwritten by the OCAPI setting 'product.inventory.stock\_level.max\_threshold'. Example: `10`.