@salesforce/b2c-tooling-sdk 2.4.0 → 2.5.0

package/node_modules/@salesforce/b2c-api-schemas/scapi/store/shopper-stores/v1.json

@@ -2,7 +2,8 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Shopper Stores",
-    "version": "1.4.0",
+    "description": "[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-stores/shopper-stores-oas-v1-public.yaml)\n\n# API Overview\n\nUse this API to access stores via search or ID lookup.\n\n## Authentication & Authorization\n\nThe Shopper Stores API requires a shopper access token from the [Shopper Login and API Access Service (SLAS).](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html)\n\nYou must include `sfcc.shopper-stores` and other relevant scope(s) in the client ID used to generate the SLAS token. For a full list of permissions, see [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)\n\nFor 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) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) in the SLAS guides.\n\n## Customization\n\n### Custom Properties\n\nThis API supports custom properties (prefixed with `c_`). For details, see [Custom Properties.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html)\n\n### Hooks\n\nFor details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)\n\n## Request Details\n\n### URL Encoding\n\nIf resource identifiers in request parameters contain commas (`,`) or percent signs (`%`), they must be URL encoded. For details, see [Encode URL Special Characters.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-encode.html)\n\n## Response Details\n\n### Personalization\n\nResponses from this API can be personalized using the [Shopper Context API.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html) By setting context attributes such as customer group, source code, or store ID, you can retrieve personalized promotions, pricing, and shipping methods. For details on how personalization interacts with caching, see [Personalized Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#personalized-caching)\n\n### Caching\n\nCaching is provided for the Shopper Stores API. For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html)\n\n### Timeouts\n\nShopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)\n\n### Error Handling\n\nError responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)\n\n## Use Cases\n\n### Search Stores by Location\n\nFind stores within a radius of a geographic coordinate.\n\n```sh\ncurl \"https://{shortCode}.api.commercecloud.salesforce.com/store/shopper-stores/v1/organizations/{organizationId}/store-search?latitude=37.7749&longitude=-122.4194&distanceUnit=mi&maxDistance=25&siteId=RefArch\" \\\n  -H \"Authorization: Bearer {access_token}\"\n```\n\n\n### Store Retrieval\n\n- Specific Lookup: Retrieve detailed information for one or more stores using unique IDs.\n- Localization: Fetch store data tailored to specific languages and regional formats using locale.\n\n### Location-Based Search\n\n- Proximity Search: Find stores within a specific radius (miles or kilometers) of a shopper.\n- Coordinate Search: Locate stores using precise latitude and longitude pairs.\n- Postal Code Search: Identify stores near a specific zip or postal code using automated geolocation mapping.\n\n### Search Optimization\n\n- Threshold Filtering: Limit results to a maximum distance from the shopper's location.\n- Pagination: Manage large result sets efficiently using limit and offset parameters.\n\n## Related APIs\n\n- [Stores (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/stores?meta=Summary) — Manage store records and attributes.",
+    "version": "1.4.2",
     "x-api-type": "Shopper",
     "x-api-family": "Store"
   },
@@ -11,6 +12,7 @@
       "url": "https://{shortCode}.api.commercecloud.salesforce.com/store/shopper-stores/v1",
       "variables": {
         "shortCode": {
+          "description": "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)",
           "default": "shortCode"
         }
       }
@@ -19,21 +21,25 @@
   "paths": {
     "/organizations/{organizationId}/stores": {
       "get": {
+        "summary": "Return stores identified by the IDs provided as input.",
         "operationId": "getStores",
         "parameters": [
           {
             "name": "organizationId",
             "in": "path",
+            "description": "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).",
             "required": true,
             "style": "simple",
             "explode": false,
             "schema": {
               "$ref": "#/components/schemas/OrganizationId"
-            }
+            },
+            "example": "f_ecom_zzxy_prd"
           },
           {
             "name": "ids",
             "in": "query",
+            "description": "The IDs of a requested stores (comma separated, max 50 IDs).",
             "required": true,
             "style": "form",
             "explode": true,
@@ -46,51 +52,55 @@
           {
             "name": "siteId",
             "in": "query",
+            "description": "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.",
             "required": true,
             "style": "form",
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/SiteId"
+            },
+            "examples": {
+              "SiteId": {
+                "value": "RefArch"
+              }
             }
           },
           {
             "name": "locale",
             "in": "query",
+            "description": "A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.",
             "required": false,
             "style": "form",
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/LocaleCode"
+            },
+            "examples": {
+              "LanguageCountry": {
+                "value": "en-US"
+              },
+              "CountryCode": {
+                "value": "US"
+              }
             }
           },
           {
             "name": "sfdc_usid",
             "in": "header",
+            "description": "A unique shopper identifier (USID) for tracking client context.\nUsed with endpoints secured with ShopperClientContextToken.\nThis header is required for all endpoints secured with ShopperClientContextToken.",
             "required": false,
             "style": "simple",
             "explode": false,
             "schema": {
               "type": "string",
-              "format": "uuid"
-            }
-          },
-          {
-            "name": "sfdc_dw_dnt",
-            "in": "header",
-            "required": false,
-            "style": "simple",
-            "explode": false,
-            "schema": {
-              "type": "string",
-              "enum": [
-                "0",
-                "1"
-              ]
+              "format": "uuid",
+              "example": "550e8400-e29b-41d4-a716-446655440000"
             }
           },
           {
             "name": "personalized",
             "in": "query",
+            "description": "Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -98,12 +108,14 @@
               "type": "string",
               "enum": [
                 "none"
-              ]
+              ],
+              "example": "none"
             }
           },
           {
             "name": "sfdc_shopper_context",
             "in": "header",
+            "description": "Shopper context information (for example clientIP, sourceCode, and customQualifiers)\npassed in from a trusted backend application.",
             "required": false,
             "style": "simple",
             "explode": false,
@@ -119,6 +131,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/StoreResult"
+                },
+                "examples": {
+                  "StoresResult": {
+                    "$ref": "#/components/examples/StoresResult"
+                  }
                 }
               }
             }
@@ -129,6 +146,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "MissingIds400": {
+                    "$ref": "#/components/examples/MissingIds400"
+                  }
                 }
               }
             }
@@ -152,21 +174,26 @@
     },
     "/organizations/{organizationId}/store-search": {
       "get": {
+        "summary": "Retrieve a list of stores for the given site that are within a configured distance of a geolocation.",
+        "description": "- The distance is interpreted either in miles or kilometers, depending on the `distanceUnit` input parameter.\n- The location is specified by either directly providing a latitude and longitude coordinate pair, or by providing a country and a postal code. If a postal code is passed, the resource looks in the system's geolocation mappings in Business Manager to find the coordinates for this postal code. If no matching geolocation is found, the resource returns an empty list of stores. If coordinates are passed, the values for country and postal code are ignored.\n\n  To verify site latitude and longitude information in Business Manager:\n  - Navigate to **Merchant Tools -> Online Marketing -> Stores**.\n  - Select the applicable site.\n  - In the **Address** tab, verify that valid information is provided in the following fields: **Address**, **City**, **Postal Code**, **State**, and **Country**. For latitude and longitude values, you can manually enter values or provide all field values to auto-populate **Latitude** and **Longitude**. You must provide valid values for all of the previous fields for latitude and longitude to auto-populate **Latitude** and **Longitude** values.\n",
         "operationId": "searchStores",
         "parameters": [
           {
             "name": "organizationId",
             "in": "path",
+            "description": "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).",
             "required": true,
             "style": "simple",
             "explode": false,
             "schema": {
               "$ref": "#/components/schemas/OrganizationId"
-            }
+            },
+            "example": "f_ecom_zzxy_prd"
           },
           {
             "name": "countryCode",
             "in": "query",
+            "description": "The two letter ISO country code, such as \"US\". This value is required when a postalCode is provided.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -177,6 +204,7 @@
           {
             "name": "distanceUnit",
             "in": "query",
+            "description": "The distance unit. Supported values are \"mi\" (miles) and \"km\" (kilometers). The default is \"km\".",
             "required": false,
             "style": "form",
             "explode": true,
@@ -187,6 +215,7 @@
           {
             "name": "latitude",
             "in": "query",
+            "description": "The geographical latitude to search for stores (value range -90.00 .. 90.00). This value is required when a longitude is provided.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -197,6 +226,7 @@
           {
             "name": "longitude",
             "in": "query",
+            "description": "The geographical longitude to search for stores (value range -180.00 .. 180.00). You must provide a longitude when a latitude is provided.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -207,6 +237,7 @@
           {
             "name": "maxDistance",
             "in": "query",
+            "description": "The area (radius) in distanceUnit where stores will be searched.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -217,6 +248,7 @@
           {
             "name": "postalCode",
             "in": "query",
+            "description": "The postal code, such as \"84121\". You must provide a countryCode when a postalCode is provided.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -227,26 +259,42 @@
           {
             "name": "siteId",
             "in": "query",
+            "description": "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.",
             "required": true,
             "style": "form",
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/SiteId"
+            },
+            "examples": {
+              "SiteId": {
+                "value": "RefArch"
+              }
             }
           },
           {
             "name": "locale",
             "in": "query",
+            "description": "A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.",
             "required": false,
             "style": "form",
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/LocaleCode"
+            },
+            "examples": {
+              "LanguageCountry": {
+                "value": "en-US"
+              },
+              "CountryCode": {
+                "value": "US"
+              }
             }
           },
           {
             "name": "limit",
             "in": "query",
+            "description": "Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -261,6 +309,7 @@
           {
             "name": "offset",
             "in": "query",
+            "description": "Used to retrieve the results based on a particular resource offset.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -274,31 +323,20 @@
           {
             "name": "sfdc_usid",
             "in": "header",
+            "description": "A unique shopper identifier (USID) for tracking client context.\nUsed with endpoints secured with ShopperClientContextToken.\nThis header is required for all endpoints secured with ShopperClientContextToken.",
             "required": false,
             "style": "simple",
             "explode": false,
             "schema": {
               "type": "string",
-              "format": "uuid"
-            }
-          },
-          {
-            "name": "sfdc_dw_dnt",
-            "in": "header",
-            "required": false,
-            "style": "simple",
-            "explode": false,
-            "schema": {
-              "type": "string",
-              "enum": [
-                "0",
-                "1"
-              ]
+              "format": "uuid",
+              "example": "550e8400-e29b-41d4-a716-446655440000"
             }
           },
           {
             "name": "personalized",
             "in": "query",
+            "description": "Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -306,12 +344,14 @@
               "type": "string",
               "enum": [
                 "none"
-              ]
+              ],
+              "example": "none"
             }
           },
           {
             "name": "sfdc_shopper_context",
             "in": "header",
+            "description": "Shopper context information (for example clientIP, sourceCode, and customQualifiers)\npassed in from a trusted backend application.",
             "required": false,
             "style": "simple",
             "explode": false,
@@ -327,6 +367,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/Stores"
+                },
+                "examples": {
+                  "StoreSearchResult": {
+                    "$ref": "#/components/examples/StoreSearchResult"
+                  }
                 }
               }
             }
@@ -337,6 +382,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "MissingPostalCode400": {
+                    "$ref": "#/components/examples/MissingPostalCode400"
+                  }
                 }
               }
             }
@@ -363,27 +413,38 @@
     "schemas": {
       "OrganizationId": {
         "type": "string",
+        "description": "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",
         "pattern": "^f_ecom_[a-z]{4}_(prd|stg|dev|s[0-9]{2}|[0-9]{3})$"
       },
       "SiteId": {
         "type": "string",
+        "description": "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": "RefArch",
         "maxLength": 32,
         "minLength": 1
       },
       "LanguageCountry": {
         "type": "string",
+        "description": "A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'.",
+        "example": "en-US",
         "pattern": "^[a-z][a-z]-[A-Z][A-Z]$"
       },
       "LanguageCode": {
         "type": "string",
+        "description": "A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766).",
+        "example": "en",
         "pattern": "^[a-z][a-z]$"
       },
       "DefaultFallback": {
         "type": "string",
         "default": "default",
+        "description": "A specialized value indicating the system default values for locales.",
+        "example": "default",
         "pattern": "^default$"
       },
       "LocaleCode": {
+        "description": "A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.",
         "oneOf": [
           {
             "$ref": "#/components/schemas/LanguageCountry"
@@ -400,14 +461,19 @@
         "type": "integer",
         "format": "int32",
         "default": 0,
+        "description": "The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.",
+        "example": 10,
         "minimum": 0
       },
       "ResultBase": {
         "type": "object",
+        "description": "Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. \nAdditionally it needs to be defined what data is returned.",
         "properties": {
           "limit": {
             "type": "integer",
-            "format": "int32"
+            "format": "int32",
+            "description": "Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.",
+            "example": 10
           },
           "total": {
             "$ref": "#/components/schemas/Total"
@@ -420,16 +486,20 @@
       },
       "CountryCode": {
         "type": "string",
+        "description": "A two letter uppercase country code conforming to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 standard.",
+        "example": "US",
         "pattern": "^[A-Z][A-Z]$"
       },
       "Distance": {
         "type": "number",
         "format": "double",
+        "description": "The distance to the given geolocation where the stores will be searched, using the unit given in the attribute 'DistanceUnit' (miles or kilometers).",
         "maximum": 20012,
         "minimum": 0
       },
       "DistanceUnit": {
         "type": "string",
+        "description": "The unit the distance attribute is measured in (either in miles or kilometers).",
         "enum": [
           "km",
           "mi"
@@ -438,32 +508,39 @@
       "Latitude": {
         "type": "number",
         "format": "double",
+        "description": "The latitude of the store.",
         "maximum": 90,
         "minimum": -90
       },
       "Longitude": {
         "type": "number",
         "format": "double",
+        "description": "The longitude of the store.",
         "maximum": 180,
         "minimum": -180
       },
       "PostalCode": {
         "type": "string",
+        "description": "The postal code of the store.",
         "maxLength": 10,
         "minLength": 3
       },
       "Store": {
         "type": "object",
+        "description": "Document representing a store.",
         "properties": {
           "address1": {
             "type": "string",
+            "description": "The primary address of the store.",
             "minLength": 1
           },
           "address2": {
-            "type": "string"
+            "type": "string",
+            "description": "The secondary address of the store."
           },
           "city": {
-            "type": "string"
+            "type": "string",
+            "description": "The city of the store."
           },
           "countryCode": {
             "$ref": "#/components/schemas/CountryCode"
@@ -475,21 +552,26 @@
             "$ref": "#/components/schemas/DistanceUnit"
           },
           "email": {
-            "type": "string"
+            "type": "string",
+            "description": "The email address of the store."
           },
           "fax": {
-            "type": "string"
+            "type": "string",
+            "description": "The fax number of the store."
           },
           "id": {
             "type": "string",
+            "description": "The id of the store.",
             "maxLength": 256,
             "minLength": 1
           },
           "image": {
-            "type": "string"
+            "type": "string",
+            "description": "The store image."
           },
           "inventoryId": {
             "type": "string",
+            "description": "The inventory list id associated with this store.",
             "maxLength": 256
           },
           "latitude": {
@@ -499,32 +581,40 @@
             "$ref": "#/components/schemas/Longitude"
           },
           "name": {
-            "type": "string"
+            "type": "string",
+            "description": "The store name."
           },
           "phone": {
-            "type": "string"
+            "type": "string",
+            "description": "The phone number of the store."
           },
           "posEnabled": {
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Whether this store uses Store Point-of-Sale."
           },
           "postalCode": {
             "allOf": [
               {
                 "$ref": "#/components/schemas/PostalCode"
               }
-            ]
+            ],
+            "description": "The postal code of the store."
           },
           "stateCode": {
-            "type": "string"
+            "type": "string",
+            "description": "The state code of the store."
           },
           "storeEvents": {
-            "type": "string"
+            "type": "string",
+            "description": "The store events."
           },
           "storeHours": {
-            "type": "string"
+            "type": "string",
+            "description": "The opening hours of the store."
           },
           "storeLocatorEnabled": {
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Whether this store should show up in store locator results."
           }
         },
         "required": [
@@ -537,9 +627,11 @@
             "$ref": "#/components/schemas/ResultBase"
           }
         ],
+        "description": "Result object containing an array of stores.",
         "properties": {
           "data": {
             "type": "array",
+            "description": "The list of stores in the search result.",
             "items": {
               "$ref": "#/components/schemas/Store"
             }
@@ -552,17 +644,25 @@
         "properties": {
           "title": {
             "type": "string",
+            "description": "A short, human-readable summary of the problem\ntype.  It will not change from occurrence to occurrence of the \nproblem, except for purposes of localization\n",
+            "example": "You do not have enough credit",
             "maxLength": 256
           },
           "type": {
             "type": "string",
+            "description": "A URI reference [RFC3986] that identifies the\nproblem type.  This specification encourages that, when\ndereferenced, it provide human-readable documentation for the\nproblem type (e.g., using HTML [W3C.REC-html5-20141028]).  When\nthis member is not present, its value is assumed to be\n\"about:blank\". It accepts relative URIs; this means\nthat they must be resolved relative to the document's base URI, as\nper [RFC3986], Section 5.\n",
+            "example": "NotEnoughMoney",
             "maxLength": 2048
           },
           "detail": {
-            "type": "string"
+            "type": "string",
+            "description": "A human-readable explanation specific to this occurrence of the problem.",
+            "example": "Your current balance is 30, but that costs 50"
           },
           "instance": {
             "type": "string",
+            "description": "A URI reference that identifies the specific\noccurrence of the problem.  It may or may not yield further\ninformation if dereferenced.  It accepts relative URIs; this means\nthat they must be resolved relative to the document's base URI, as\nper [RFC3986], Section 5.\n",
+            "example": "/account/12345/msgs/abc",
             "maxLength": 2048
           }
         },
@@ -576,6 +676,8 @@
         "type": "integer",
         "format": "int32",
         "default": 0,
+        "description": "The zero-based index of the first hit/data to include in the result.",
+        "example": 0,
         "minimum": 0
       },
       "PaginatedResultBase": {
@@ -584,6 +686,7 @@
             "$ref": "#/components/schemas/ResultBase"
           }
         ],
+        "description": "Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. \nIf you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.",
         "properties": {
           "offset": {
             "$ref": "#/components/schemas/Offset"
@@ -601,9 +704,11 @@
             "$ref": "#/components/schemas/PaginatedResultBase"
           }
         ],
+        "description": "Result object containing an paginated array of stores.",
         "properties": {
           "data": {
             "type": "array",
+            "description": "The list of stores in the search result.",
             "items": {
               "$ref": "#/components/schemas/Store"
             }
@@ -615,16 +720,19 @@
       "organizationId": {
         "name": "organizationId",
         "in": "path",
+        "description": "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).",
         "required": true,
         "style": "simple",
         "explode": false,
         "schema": {
           "$ref": "#/components/schemas/OrganizationId"
-        }
+        },
+        "example": "f_ecom_zzxy_prd"
       },
       "ids": {
         "name": "ids",
         "in": "query",
+        "description": "The IDs of a requested stores (comma separated, max 50 IDs).",
         "required": true,
         "style": "form",
         "explode": true,
@@ -637,26 +745,42 @@
       "siteId": {
         "name": "siteId",
         "in": "query",
+        "description": "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.",
         "required": true,
         "style": "form",
         "explode": true,
         "schema": {
           "$ref": "#/components/schemas/SiteId"
+        },
+        "examples": {
+          "SiteId": {
+            "value": "RefArch"
+          }
         }
       },
       "locale": {
         "name": "locale",
         "in": "query",
+        "description": "A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.",
         "required": false,
         "style": "form",
         "explode": true,
         "schema": {
           "$ref": "#/components/schemas/LocaleCode"
+        },
+        "examples": {
+          "LanguageCountry": {
+            "value": "en-US"
+          },
+          "CountryCode": {
+            "value": "US"
+          }
         }
       },
       "countryCode": {
         "name": "countryCode",
         "in": "query",
+        "description": "The two letter ISO country code, such as \"US\". This value is required when a postalCode is provided.",
         "required": false,
         "style": "form",
         "explode": true,
@@ -667,6 +791,7 @@
       "distanceUnit": {
         "name": "distanceUnit",
         "in": "query",
+        "description": "The distance unit. Supported values are \"mi\" (miles) and \"km\" (kilometers). The default is \"km\".",
         "required": false,
         "style": "form",
         "explode": true,
@@ -677,6 +802,7 @@
       "latitude": {
         "name": "latitude",
         "in": "query",
+        "description": "The geographical latitude to search for stores (value range -90.00 .. 90.00). This value is required when a longitude is provided.",
         "required": false,
         "style": "form",
         "explode": true,
@@ -687,6 +813,7 @@
       "longitude": {
         "name": "longitude",
         "in": "query",
+        "description": "The geographical longitude to search for stores (value range -180.00 .. 180.00). You must provide a longitude when a latitude is provided.",
         "required": false,
         "style": "form",
         "explode": true,
@@ -697,6 +824,7 @@
       "maxDistance": {
         "name": "maxDistance",
         "in": "query",
+        "description": "The area (radius) in distanceUnit where stores will be searched.",
         "required": false,
         "style": "form",
         "explode": true,
@@ -707,6 +835,7 @@
       "postalCode": {
         "name": "postalCode",
         "in": "query",
+        "description": "The postal code, such as \"84121\". You must provide a countryCode when a postalCode is provided.",
         "required": false,
         "style": "form",
         "explode": true,
@@ -717,31 +846,20 @@
       "sfdcUsid": {
         "name": "sfdc_usid",
         "in": "header",
+        "description": "A unique shopper identifier (USID) for tracking client context.\nUsed with endpoints secured with ShopperClientContextToken.\nThis header is required for all endpoints secured with ShopperClientContextToken.",
         "required": false,
         "style": "simple",
         "explode": false,
         "schema": {
           "type": "string",
-          "format": "uuid"
-        }
-      },
-      "sfdcDwDnt": {
-        "name": "sfdc_dw_dnt",
-        "in": "header",
-        "required": false,
-        "style": "simple",
-        "explode": false,
-        "schema": {
-          "type": "string",
-          "enum": [
-            "0",
-            "1"
-          ]
+          "format": "uuid",
+          "example": "550e8400-e29b-41d4-a716-446655440000"
         }
       },
       "personalized": {
         "name": "personalized",
         "in": "query",
+        "description": "Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.",
         "required": false,
         "style": "form",
         "explode": true,
@@ -749,12 +867,14 @@
           "type": "string",
           "enum": [
             "none"
-          ]
+          ],
+          "example": "none"
         }
       },
       "sfdcShopperContext": {
         "name": "sfdc_shopper_context",
         "in": "header",
+        "description": "Shopper context information (for example clientIP, sourceCode, and customQualifiers)\npassed in from a trusted backend application.",
         "required": false,
         "style": "simple",
         "explode": false,
@@ -763,9 +883,191 @@
         }
       }
     },
+    "examples": {
+      "StoresResult": {
+        "value": {
+          "data": [
+            {
+              "address1": "1487 Bay St",
+              "city": "Springfield",
+              "countryCode": "US",
+              "distance": 147.03,
+              "distanceUnit": "km",
+              "id": "store9",
+              "name": "Springfield Media Store",
+              "phone": "+1-413-413-6916",
+              "posEnabled": false,
+              "postalCode": "01109",
+              "stateCode": "MA",
+              "storeEvents": "Here are some store events.",
+              "storeHours": "Here are the store hours",
+              "storeLocatorEnabled": true
+            },
+            {
+              "address1": "70 Wood Ave",
+              "city": "Bridgeport",
+              "countryCode": "US",
+              "distance": 198.36,
+              "distanceUnit": "km",
+              "email": "store1@company.com",
+              "id": "store11",
+              "name": "Electronics Super Store",
+              "phone": "+1-203-965-7014",
+              "posEnabled": false,
+              "postalCode": "06605",
+              "stateCode": "CT",
+              "storeLocatorEnabled": true
+            },
+            {
+              "address1": "239 Bridge St",
+              "city": "Manchester",
+              "countryCode": "US",
+              "distance": 219,
+              "distanceUnit": "km",
+              "id": "store8",
+              "name": "Gardena Mart",
+              "phone": "+1-603-715-9773",
+              "posEnabled": false,
+              "postalCode": "03104",
+              "stateCode": "NH",
+              "storeLocatorEnabled": true
+            },
+            {
+              "address1": "150 Winthrop Ave",
+              "city": "Lawrence",
+              "countryCode": "US",
+              "distance": 242.77,
+              "distanceUnit": "km",
+              "id": "store6",
+              "name": "Khale Street Electronics",
+              "phone": "+1-978-580-2704",
+              "posEnabled": false,
+              "postalCode": "01843",
+              "stateCode": "MA",
+              "storeLocatorEnabled": true
+            },
+            {
+              "address1": "110 Smith St",
+              "city": "Providence",
+              "countryCode": "US",
+              "distance": 245.02,
+              "distanceUnit": "km",
+              "email": "store2@company.com",
+              "id": "store2",
+              "name": "Super Electronics",
+              "phone": "+1-401-312-6284",
+              "posEnabled": false,
+              "postalCode": "02903",
+              "stateCode": "RI",
+              "storeLocatorEnabled": true
+            }
+          ],
+          "limit": 5,
+          "total": 12
+        }
+      },
+      "MissingIds400": {
+        "value": {
+          "detail": "Missing required query parameter(s): 'ids'",
+          "title": "Bad Request",
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/missing-query-parameter"
+        }
+      },
+      "StoreSearchResult": {
+        "value": {
+          "data": [
+            {
+              "address1": "1487 Bay St",
+              "city": "Springfield",
+              "countryCode": "US",
+              "distance": 147.03,
+              "distanceUnit": "km",
+              "id": "store9",
+              "name": "Springfield Media Store",
+              "phone": "+1-413-413-6916",
+              "posEnabled": false,
+              "postalCode": "01109",
+              "stateCode": "MA",
+              "storeEvents": "Here are some store events.",
+              "storeHours": "Here are the store hours",
+              "storeLocatorEnabled": true
+            },
+            {
+              "address1": "70 Wood Ave",
+              "city": "Bridgeport",
+              "countryCode": "US",
+              "distance": 198.36,
+              "distanceUnit": "km",
+              "email": "store1@company.com",
+              "id": "store11",
+              "name": "Electronics Super Store",
+              "phone": "+1-203-965-7014",
+              "posEnabled": false,
+              "postalCode": "06605",
+              "stateCode": "CT",
+              "storeLocatorEnabled": true
+            },
+            {
+              "address1": "239 Bridge St",
+              "city": "Manchester",
+              "countryCode": "US",
+              "distance": 219,
+              "distanceUnit": "km",
+              "id": "store8",
+              "name": "Gardena Mart",
+              "phone": "+1-603-715-9773",
+              "posEnabled": false,
+              "postalCode": "03104",
+              "stateCode": "NH",
+              "storeLocatorEnabled": true
+            },
+            {
+              "address1": "150 Winthrop Ave",
+              "city": "Lawrence",
+              "countryCode": "US",
+              "distance": 242.77,
+              "distanceUnit": "km",
+              "id": "store6",
+              "name": "Khale Street Electronics",
+              "phone": "+1-978-580-2704",
+              "posEnabled": false,
+              "postalCode": "01843",
+              "stateCode": "MA",
+              "storeLocatorEnabled": true
+            },
+            {
+              "address1": "110 Smith St",
+              "city": "Providence",
+              "countryCode": "US",
+              "distance": 245.02,
+              "distanceUnit": "km",
+              "email": "store2@company.com",
+              "id": "store2",
+              "name": "Super Electronics",
+              "phone": "+1-401-312-6284",
+              "posEnabled": false,
+              "postalCode": "02903",
+              "stateCode": "RI",
+              "storeLocatorEnabled": true
+            }
+          ],
+          "limit": 5,
+          "offset": 0,
+          "total": 12
+        }
+      },
+      "MissingPostalCode400": {
+        "value": {
+          "title": "Missing Postal Code",
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/missing-postal-code",
+          "detail": "The input parameter 'postal_code' is required when no coordinates are provided."
+        }
+      }
+    },
     "securitySchemes": {
       "ShopperToken": {
         "type": "oauth2",
+        "description": "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. \nFor a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary).\nA 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.\nThe `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.\n",
         "flows": {
           "clientCredentials": {
             "tokenUrl": "https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token",
@@ -784,6 +1086,7 @@
       },
       "ShopperClientContextToken": {
         "type": "oauth2",
+        "description": "ShopperClientContextToken is a separate security scheme used to track and validate client context information.\nIt is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows.\nFor authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary).\nThis token allows access to Shopper API endpoints for guest shoppers only.\n",
         "flows": {
           "clientCredentials": {
             "tokenUrl": "https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client_context",