@salesforce/b2c-tooling-sdk 2.3.0 → 2.5.0

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

@@ -2,6 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Stores",
+    "description": "[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/stores/stores-oas-v1-public.yaml)\n\n# API Overview\n\nThe Stores API provides access to store data within the Data API family. This API allows you to retrieve and search for stores using complex query expressions.\n\n## Features\n\n- **Get Stores**: Retrieve a paginated list of all stores in an organization\n- **Store Search**: Search for stores using flexible query expressions\n- **Complex Queries**: Support for term queries, text queries, boolean queries, and range filters\n- **Sorting**: Sort results by any searchable field\n- **Pagination**: Built-in pagination support with configurable limits and offsets\n- **Field Selection**: Use the select parameter to retrieve only specific fields\n\n## Endpoints\n\n### GET /organizations/{organizationId}/stores\n\nRetrieve a list of all stores within the specified organization. This endpoint returns all stores without any filtering and supports pagination for results.\n\n**Parameters:**\n- `organizationId` (required) - The organization identifier\n- `siteId` (required) - The site identifier\n- `offset` (optional) - Zero-based index of the first store to return (default: 0)\n- `limit` (optional) - Maximum number of stores to return (default: 50, max: 200)\n- `select` (optional) - Property selector to retrieve only specific fields\n\n### GET /organizations/{organizationId}/stores/{id}\n\nRetrieve detailed information for a specific store by ID.\n\n**Parameters:**\n- `organizationId` (required) - The organization identifier\n- `siteId` (required) - The site identifier\n- `id` (required) - The ID of the store to retrieve\n- `select` (optional) - Property selector to retrieve only specific fields\n\n**Error Responses:**\n- `404` - Store not found when the specified store ID does not exist\n\n### POST /organizations/{organizationId}/store-search\n\nSearch for stores using flexible query expressions with support for filtering, sorting, and pagination.\n\n## Searchable Fields\n\nThe following fields are searchable in store queries:\n\n- `id` - Store identifier (String)\n- `name` - Store name (String)\n- `address1` - Primary address (String)\n- `address2` - Secondary address (String)\n- `city` - City name (String)\n- `stateCode` - State code (String)\n- `postalCode` - Postal code (String)\n- `countryCode` - Country code (String)\n- `phone` - Phone number (String)\n- `fax` - Fax number (String)\n- `email` - Email address (String)\n- `latitude` - Geographic latitude (Double)\n- `longitude` - Geographic longitude (Double)\n- `inventoryId` - Associated inventory list ID (String)\n- `storeHours` - Store hours information (String)\n- `storeEvents` - Store events information (String)\n\n## Authentication\n\nThis API uses OAuth 2.0 client credentials flow via Account Manager with the following scope:\n- `sfcc.stores` - Read access to store resources\n\n## Related APIs\n\n- **Shopper Stores API**: Shopper-facing store search with geolocation support\n- **Inventory APIs**: Manage inventory associated with stores",
     "version": "1.2.0",
     "x-api-type": "Admin",
     "x-api-family": "Store"
@@ -19,26 +20,36 @@
   "paths": {
     "/organizations/{organizationId}/stores": {
       "get": {
+        "summary": "Get Stores",
+        "description": "Retrieve a list of all stores in an organization. Pagination is supported for results.\n\nThis endpoint returns all stores within the specified organization without any filtering.\nUse the offset and limit parameters to control pagination.\n",
         "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": "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"
+              }
             }
           },
           {
@@ -49,11 +60,17 @@
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/Select"
+            },
+            "examples": {
+              "select": {
+                "value": "(**)"
+              }
             }
           },
           {
             "name": "limit",
             "in": "query",
+            "description": "Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 50.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -68,6 +85,7 @@
           {
             "name": "offset",
             "in": "query",
+            "description": "Used to retrieve the results based on a particular resource offset.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -86,6 +104,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/StoreResult"
+                },
+                "examples": {
+                  "StoreResultSuccess": {
+                    "$ref": "#/components/examples/StoreResultSuccess"
+                  }
                 }
               }
             }
@@ -109,31 +132,42 @@
     },
     "/organizations/{organizationId}/stores/{id}": {
       "get": {
+        "summary": "Get Store",
+        "description": "Retrieve information for a specific store by ID.\n\nThis endpoint returns detailed information about a single store within the specified organization.\nUse the select parameter to retrieve only specific fields.\n",
         "operationId": "getStore",
         "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": "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": "id",
             "in": "path",
+            "description": "The ID of the store to retrieve.",
             "required": true,
             "style": "simple",
             "explode": false,
@@ -149,6 +183,11 @@
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/Select"
+            },
+            "examples": {
+              "select": {
+                "value": "(**)"
+              }
             }
           }
         ],
@@ -159,6 +198,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/Store"
+                },
+                "examples": {
+                  "StoreSuccess": {
+                    "$ref": "#/components/examples/StoreSuccess"
+                  }
                 }
               }
             }
@@ -175,6 +219,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "StoreNotFound": {
+                    "$ref": "#/components/examples/StoreNotFound"
+                  }
                 }
               }
             }
@@ -190,31 +239,42 @@
         ]
       },
       "put": {
+        "summary": "Create or Replace Store",
+        "description": "Create a new store or replace an existing store.\n\nIf a store with the specified ID does not exist, a new store is created (returns 201).\nIf a store with the specified ID already exists, it is replaced with the provided data (returns 200).\n",
         "operationId": "createOrReplaceStore",
         "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": "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": "id",
             "in": "path",
+            "description": "The ID of the store to create or replace.",
             "required": true,
             "style": "simple",
             "explode": false,
@@ -224,10 +284,16 @@
           }
         ],
         "requestBody": {
+          "description": "The store data to create or replace.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/StoreRequest"
+              },
+              "examples": {
+                "CreateStore": {
+                  "$ref": "#/components/examples/CreateStore"
+                }
               }
             }
           },
@@ -240,6 +306,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/Store"
+                },
+                "examples": {
+                  "ReplaceStoreSuccess": {
+                    "$ref": "#/components/examples/ReplaceStoreSuccess"
+                  }
                 }
               }
             }
@@ -250,6 +321,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/Store"
+                },
+                "examples": {
+                  "CreateStoreSuccess": {
+                    "$ref": "#/components/examples/CreateStoreSuccess"
+                  }
                 }
               }
             }
@@ -260,6 +336,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "IdConflict": {
+                    "$ref": "#/components/examples/IdConflict"
+                  }
                 }
               }
             }
@@ -280,31 +361,42 @@
         ]
       },
       "delete": {
+        "summary": "Delete Store",
+        "description": "Delete a store by ID.\n\nPermanently removes the store with the specified ID from the organization.\n",
         "operationId": "deleteStore",
         "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": "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": "id",
             "in": "path",
+            "description": "The ID of the store to delete.",
             "required": true,
             "style": "simple",
             "explode": false,
@@ -329,6 +421,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "StoreNotFound": {
+                    "$ref": "#/components/examples/StoreNotFound"
+                  }
                 }
               }
             }
@@ -343,31 +440,42 @@
         ]
       },
       "patch": {
+        "summary": "Update Store",
+        "description": "Update an existing store.\n\nUpdates the store with the specified ID using the properties provided in the request body.\nOnly the properties included in the request body are updated; all other properties remain unchanged.\n",
         "operationId": "updateStore",
         "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": "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": "id",
             "in": "path",
+            "description": "The ID of the store to update.",
             "required": true,
             "style": "simple",
             "explode": false,
@@ -377,10 +485,16 @@
           }
         ],
         "requestBody": {
+          "description": "The store data to update.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/StoreRequest"
+              },
+              "examples": {
+                "UpdateStore": {
+                  "$ref": "#/components/examples/UpdateStore"
+                }
               }
             }
           },
@@ -393,6 +507,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/Store"
+                },
+                "examples": {
+                  "UpdateStoreSuccess": {
+                    "$ref": "#/components/examples/UpdateStoreSuccess"
+                  }
                 }
               }
             }
@@ -403,6 +522,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "IdConflict": {
+                    "$ref": "#/components/examples/IdConflict"
+                  }
                 }
               }
             }
@@ -419,6 +543,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "StoreNotFound": {
+                    "$ref": "#/components/examples/StoreNotFound"
+                  }
                 }
               }
             }
@@ -435,34 +564,53 @@
     },
     "/organizations/{organizationId}/store-search": {
       "post": {
+        "summary": "Search Stores",
+        "description": "Searches for stores.\n\nThe query attribute specifies a complex query that can be used to narrow down the search. This is the list of\nsearchable attributes:\n\n- address1 - String\n- address2 - String\n- city - String\n- countryCode - String\n- email - String\n- fax - String\n- id - String\n- inventoryId - String\n- latitude - double\n- longitude - double\n- name - String\n- phone - String\n- postalCode - String\n- stateCode - String\n- storeHours - String\n- storeEvents - String\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": "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"
+              }
             }
           }
         ],
         "requestBody": {
+          "description": "The search request document",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/StoreSearchRequest"
+              },
+              "examples": {
+                "StoreSearchByName": {
+                  "$ref": "#/components/examples/StoreSearchByName"
+                },
+                "StoreSearchByCity": {
+                  "$ref": "#/components/examples/StoreSearchByCity"
+                }
               }
             }
           },
@@ -475,6 +623,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/StoreSearchResult"
+                },
+                "examples": {
+                  "StoreSearchResultSuccess": {
+                    "$ref": "#/components/examples/StoreSearchResultSuccess"
+                  }
                 }
               }
             }
@@ -485,6 +638,17 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "MalformedSearchParameter": {
+                    "$ref": "#/components/examples/MalformedSearchParameter"
+                  },
+                  "InvalidQueryField": {
+                    "$ref": "#/components/examples/InvalidQueryField"
+                  },
+                  "FieldNotSortable": {
+                    "$ref": "#/components/examples/FieldNotSortable"
+                  }
                 }
               }
             }
@@ -511,15 +675,21 @@
     "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
       },
       "Select": {
         "type": "string",
+        "description": "The property selector declaring which fields are included into the response payload. You can specify a single field name, a comma-separated list of names or work with wildcards. You can also specify array operations and filter expressions. The actual selector value must be enclosed within parentheses. For more information, please read the documentation about property selectors [here](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html).",
+        "example": "(name,id,variationAttributes.(**))",
         "minLength": 1,
         "pattern": "^[(].*[)]$"
       },
@@ -527,14 +697,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"
@@ -549,6 +724,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": {
@@ -557,6 +734,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"
@@ -570,26 +748,37 @@
       },
       "StoreId": {
         "type": "string",
+        "description": "The ID of the store.",
+        "example": "store-001",
         "maxLength": 256,
         "minLength": 1
       },
       "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]$"
       },
       "InventoryId": {
         "type": "string",
+        "description": "The inventory list ID associated with the store.",
+        "example": "inventory-001",
         "maxLength": 256,
         "minLength": 1
       },
       "MarkupText": {
         "type": "object",
+        "description": "Document representing markup text.",
         "properties": {
           "markup": {
-            "type": "string"
+            "type": "string",
+            "description": "The rendered HTML.",
+            "example": ""
           },
           "source": {
-            "type": "string"
+            "type": "string",
+            "description": "The raw markup text.",
+            "example": ""
           }
         },
         "required": [
@@ -600,30 +789,47 @@
       "Email": {
         "type": "string",
         "format": "email",
+        "description": "Email address to contact the store.",
+        "example": "store@example.com",
         "maxLength": 256
       },
       "MediaFile": {
         "type": "object",
+        "description": "Document representing media file.",
         "properties": {
           "absUrl": {
-            "type": "string"
+            "type": "string",
+            "description": "The absolute URL with request protocol.",
+            "example": "https://www.example-image.com/images/apple-ipod-classic.jpg"
           },
           "alt": {
             "type": "object",
             "additionalProperties": {
               "type": "string"
+            },
+            "description": "The alternative image text.",
+            "example": {
+              "en_US": "iPod"
             }
           },
           "disBaseUrl": {
-            "type": "string"
+            "type": "string",
+            "description": "The Dynamic Image Service (DIS) base URL for product images only.",
+            "example": "https://www.dis-base-url/images/apple-ipod-clasic.jpg"
           },
           "path": {
-            "type": "string"
+            "type": "string",
+            "description": "The raw media file path.",
+            "example": "/images/apple-ipod-classic.jpg"
           },
           "title": {
             "type": "object",
             "additionalProperties": {
               "type": "string"
+            },
+            "description": "The image title.",
+            "example": {
+              "en_US": "iPod"
             }
           }
         },
@@ -633,29 +839,44 @@
       },
       "Store": {
         "type": "object",
-        "additionalProperties": {},
+        "additionalProperties": {
+          "description": "This type supports additional properties passed along with the defined properties of this API.\nTo indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`.\nThe type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.",
+          "example": "c_trackingId",
+          "title": "Additional Property Support"
+        },
         "properties": {
           "id": {
             "allOf": [
               {
                 "$ref": "#/components/schemas/StoreId"
               }
-            ]
+            ],
+            "title": "ID"
           },
           "name": {
             "type": "string",
+            "description": "The name of the store.",
+            "example": "Downtown Store",
             "maxLength": 256
           },
           "address1": {
             "type": "string",
-            "maxLength": 256
+            "description": "The first line of the store address.",
+            "example": "123 Main St",
+            "maxLength": 256,
+            "title": "address1"
           },
           "address2": {
             "type": "string",
-            "maxLength": 256
+            "description": "The second line of the store address.",
+            "example": "Suite 100",
+            "maxLength": 256,
+            "title": "address2"
           },
           "city": {
             "type": "string",
+            "description": "The city of the store.",
+            "example": "San Francisco",
             "maxLength": 256
           },
           "countryCode": {
@@ -663,29 +884,41 @@
           },
           "phone": {
             "type": "string",
+            "description": "The phone number of the store.",
+            "example": "+1-555-123-4567",
             "maxLength": 256
           },
           "postalCode": {
             "type": "string",
+            "description": "The postal code of the store.",
+            "example": "94102",
             "maxLength": 10
           },
           "stateCode": {
             "type": "string",
+            "description": "The state code of the store.",
+            "example": "CA",
             "maxLength": 256
           },
           "fax": {
             "type": "string",
+            "description": "The fax number of the store.",
+            "example": "+1-555-123-4568",
             "maxLength": 256
           },
           "longitude": {
             "type": "number",
             "format": "double",
+            "description": "The longitude of the store.",
+            "example": -122.4194,
             "maximum": 180,
             "minimum": -180
           },
           "latitude": {
             "type": "number",
             "format": "double",
+            "description": "The latitude of the store.",
+            "example": 37.7749,
             "maximum": 90,
             "minimum": -90
           },
@@ -694,19 +927,22 @@
               {
                 "$ref": "#/components/schemas/InventoryId"
               }
-            ]
+            ],
+            "title": "inventoryListID"
           },
           "storeHours": {
             "type": "object",
             "additionalProperties": {
               "$ref": "#/components/schemas/MarkupText"
-            }
+            },
+            "description": "The localized store opening hours."
           },
           "storeEvents": {
             "type": "object",
             "additionalProperties": {
               "$ref": "#/components/schemas/MarkupText"
-            }
+            },
+            "description": "The localized store events."
           },
           "email": {
             "allOf": [
@@ -720,22 +956,31 @@
               {
                 "$ref": "#/components/schemas/MediaFile"
               }
-            ]
+            ],
+            "description": "The image URL associated with the store."
           },
           "storeLocatorEnabled": {
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Specifies whether the store appears in store locator searches (true) or not (false).",
+            "example": true
           },
           "posEnabled": {
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Specifies whether the store uses Store product for Point-of-Sale (true) or not (false).",
+            "example": true
           },
           "creationDate": {
             "type": "string",
             "format": "date-time",
+            "description": "Returns the value of attribute 'creationDate'.",
+            "example": "2023-01-15T10:30:00Z",
             "readOnly": true
           },
           "lastModified": {
             "type": "string",
             "format": "date-time",
+            "description": "Returns the value of attribute 'lastModified'.",
+            "example": "2024-06-20T14:45:00Z",
             "readOnly": true
           }
         },
@@ -749,9 +994,11 @@
             "$ref": "#/components/schemas/PaginatedResultBase"
           }
         ],
+        "description": "Document representing a paginated list of stores.",
         "properties": {
           "data": {
             "type": "array",
+            "description": "The array of store instances.",
             "items": {
               "$ref": "#/components/schemas/Store"
             }
@@ -767,17 +1014,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
           }
         },
@@ -789,29 +1044,45 @@
       },
       "StoreRequest": {
         "type": "object",
-        "additionalProperties": {},
+        "additionalProperties": {
+          "description": "This type supports additional properties passed along with the defined properties of this API.\nTo indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`.\nThe type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.",
+          "example": "c_trackingId",
+          "title": "Additional Property Support"
+        },
+        "description": "Document representing a store request body for create or update operations.",
         "properties": {
           "id": {
             "allOf": [
               {
                 "$ref": "#/components/schemas/StoreId"
               }
-            ]
+            ],
+            "title": "ID"
           },
           "name": {
             "type": "string",
+            "description": "The name of the store.",
+            "example": "Downtown Store",
             "maxLength": 256
           },
           "address1": {
             "type": "string",
-            "maxLength": 256
+            "description": "The first line of the store address.",
+            "example": "123 Main St",
+            "maxLength": 256,
+            "title": "address1"
           },
           "address2": {
             "type": "string",
-            "maxLength": 256
+            "description": "The second line of the store address.",
+            "example": "Suite 100",
+            "maxLength": 256,
+            "title": "address2"
           },
           "city": {
             "type": "string",
+            "description": "The city of the store.",
+            "example": "San Francisco",
             "maxLength": 256
           },
           "countryCode": {
@@ -819,29 +1090,41 @@
           },
           "phone": {
             "type": "string",
+            "description": "The phone number of the store.",
+            "example": "+1-555-123-4567",
             "maxLength": 256
           },
           "postalCode": {
             "type": "string",
+            "description": "The postal code of the store.",
+            "example": "94102",
             "maxLength": 10
           },
           "stateCode": {
             "type": "string",
+            "description": "The state code of the store.",
+            "example": "CA",
             "maxLength": 256
           },
           "fax": {
             "type": "string",
+            "description": "The fax number of the store.",
+            "example": "+1-555-123-4568",
             "maxLength": 256
           },
           "longitude": {
             "type": "number",
             "format": "double",
+            "description": "The longitude of the store.",
+            "example": -122.4194,
             "maximum": 180,
             "minimum": -180
           },
           "latitude": {
             "type": "number",
             "format": "double",
+            "description": "The latitude of the store.",
+            "example": 37.7749,
             "maximum": 90,
             "minimum": -90
           },
@@ -850,19 +1133,22 @@
               {
                 "$ref": "#/components/schemas/InventoryId"
               }
-            ]
+            ],
+            "title": "inventoryListID"
           },
           "storeHours": {
             "type": "object",
             "additionalProperties": {
               "$ref": "#/components/schemas/MarkupText"
-            }
+            },
+            "description": "The localized store opening hours."
           },
           "storeEvents": {
             "type": "object",
             "additionalProperties": {
               "$ref": "#/components/schemas/MarkupText"
-            }
+            },
+            "description": "The localized store events."
           },
           "email": {
             "allOf": [
@@ -876,13 +1162,18 @@
               {
                 "$ref": "#/components/schemas/MediaFile"
               }
-            ]
+            ],
+            "description": "The image URL associated with the store."
           },
           "storeLocatorEnabled": {
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Specifies whether the store appears in store locator searches (true) or not (false).",
+            "example": true
           },
           "posEnabled": {
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Specifies whether the store uses Store product for Point-of-Sale (true) or not (false).",
+            "example": true
           }
         },
         "required": [
@@ -892,6 +1183,28 @@
       "Query": {
         "type": "object",
         "additionalProperties": false,
+        "description": "A set of objects that define criteria used to select records. A query can contain one of the following:\n* `MatchAllQuery`\n - Matches all documents.\n* `TermQuery`\n - Matches one or more documents against one or more document fields.\n* `TextQuery`\n - Matches text against one or more fields.\n* `BoolQuery`\n - Allows construction of a logical expression of multiple queries.\n* `FilteredQuery`\n - Allows a filter to be applied to a query.\n* `NestedQuery`\n - Allows you to query on nested documents.\n - _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._",
+        "example": {
+          "filteredQuery": {
+            "query": {
+              "textQuery": {
+                "fields": [
+                  "couponId"
+                ],
+                "searchPhrase": "disabled"
+              }
+            },
+            "filter": {
+              "termFilter": {
+                "field": "enabled",
+                "operator": "is",
+                "values": [
+                  false
+                ]
+              }
+            }
+          }
+        },
         "maxProperties": 1,
         "minProperties": 1,
         "properties": {
@@ -918,21 +1231,60 @@
       "BoolQuery": {
         "type": "object",
         "additionalProperties": false,
+        "description": "A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:\n  \n  - `must`, which combines as an `AND` operator.\n  - `should`, which combines as an `OR` operator.\n  - `must_not`, which combines as a `NOT` operator.\n  \nIf `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:\n\n    (must-1 AND must-1 AND ...)\n      AND (should-1 OR should-2 OR ...)\n      AND NOT (must_not-1 OR must_not-2 OR ...)\n",
+        "example": {
+          "value": {
+            "must": [
+              {
+                "textQuery": {
+                  "fields": [
+                    "couponId"
+                  ],
+                  "searchPhrase": "DEAL"
+                }
+              },
+              {
+                "textQuery": {
+                  "fields": [
+                    "description"
+                  ],
+                  "searchPhrase": "Big bargain deal"
+                }
+              }
+            ],
+            "mustNot": [
+              {
+                "termQuery": {
+                  "fields": [
+                    "enabled"
+                  ],
+                  "operator": "is",
+                  "values": [
+                    false
+                  ]
+                }
+              }
+            ]
+          }
+        },
         "properties": {
           "must": {
             "type": "array",
+            "description": "List of queries to be evaluated as an `AND` operator.",
             "items": {
               "$ref": "#/components/schemas/Query"
             }
           },
           "mustNot": {
             "type": "array",
+            "description": "List of queries to be evaluated as a `NOT` operator.",
             "items": {
               "$ref": "#/components/schemas/Query"
             }
           },
           "should": {
             "type": "array",
+            "description": "List of queries to be evaluated as an `OR` operator.",
             "items": {
               "$ref": "#/components/schemas/Query"
             }
@@ -942,6 +1294,7 @@
       "Filter": {
         "type": "object",
         "additionalProperties": false,
+        "description": "Contains a set of objects that define criteria used to select records. A filter can contain one of the following:\n  * `TermFilter`\n   - Matches records where a field (or fields) exactly matches some simple value (including `null`).\n  * `RangeFilter`\n   - Matches records where a field value lies within a specified range.\n  * `Range2Filter`\n   - Matches records in a specified range across fields.\n  * `QueryFilter`\n   - Matches records based on a query.\n  * `BoolFilter`\n   - Provides filtering of records using a set of filters combined using a logical operator.",
         "maxProperties": 1,
         "minProperties": 1,
         "properties": {
@@ -965,20 +1318,49 @@
       "BoolFilter": {
         "type": "object",
         "additionalProperties": false,
+        "description": "Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.",
+        "example": {
+          "value": {
+            "operator": "and",
+            "filters": [
+              {
+                "termFilter": {
+                  "field": "id",
+                  "operator": "is",
+                  "values": [
+                    "myId"
+                  ]
+                }
+              },
+              {
+                "termFilter": {
+                  "field": "couponId",
+                  "operator": "is",
+                  "values": [
+                    "couponOne"
+                  ]
+                }
+              }
+            ]
+          }
+        },
         "properties": {
           "filters": {
             "type": "array",
+            "description": "A list of filters that are logically combined by an operator.",
             "items": {
               "$ref": "#/components/schemas/Filter"
             }
           },
           "operator": {
             "type": "string",
+            "description": "The logical operator that is used to combine the filters.",
             "enum": [
               "and",
               "or",
               "not"
-            ]
+            ],
+            "example": "and"
           }
         },
         "required": [
@@ -987,6 +1369,7 @@
       },
       "QueryFilter": {
         "type": "object",
+        "description": "Wraps any query and allows it to be used as a filter.",
         "properties": {
           "query": {
             "$ref": "#/components/schemas/Query"
@@ -998,45 +1381,71 @@
       },
       "Field": {
         "type": "string",
+        "description": "Name of the field. Might be a custom field name prefixed with c_.",
+        "example": "couponId",
         "maxLength": 260
       },
       "Range2Filter": {
         "type": "object",
         "additionalProperties": false,
+        "description": "Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.\n\nThe first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.\n\nThe second range (R2) is defined by `fromValue` and `toValue`.\n\nThe filter mode specifies the method used to compare the two ranges:\n\n* `overlap`: R1 overlaps fully or partially with R2.\n* `containing`: R1 contains R2.\n* `contained`: R1 is contained in R2.\n\nThe range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.\n\nA range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.",
+        "example": {
+          "fromField": "validFrom",
+          "toField": "validTo",
+          "filterMode": "overlap",
+          "fromValue": "2007-01-01T00:00:00.000Z",
+          "toValue": "2017-01-01T00:00:00.000Z"
+        },
         "properties": {
           "filterMode": {
             "type": "string",
             "default": "overlap",
+            "description": "Compare mode: overlap, containing, or contained.",
             "enum": [
               "overlap",
               "containing",
               "contained"
-            ]
+            ],
+            "example": "overlap"
           },
           "fromField": {
             "allOf": [
               {
                 "$ref": "#/components/schemas/Field"
               }
-            ]
+            ],
+            "description": "The field name of the field that starts the first range.",
+            "example": "validFrom"
           },
           "fromInclusive": {
             "type": "boolean",
-            "default": true
+            "default": true,
+            "description": "A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.",
+            "example": true
+          },
+          "fromValue": {
+            "description": "The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.",
+            "example": "2007-01-01T00:00:00.000Z"
           },
-          "fromValue": {},
           "toField": {
             "allOf": [
               {
                 "$ref": "#/components/schemas/Field"
               }
-            ]
+            ],
+            "description": "The field name of the field that ends the first range.",
+            "example": "validTo"
           },
           "toInclusive": {
             "type": "boolean",
-            "default": true
+            "default": true,
+            "description": "A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.",
+            "example": true
           },
-          "toValue": {}
+          "toValue": {
+            "description": "The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.",
+            "example": "2017-01-01T00:00:00.000Z"
+          }
         },
         "required": [
           "fromField",
@@ -1045,49 +1454,64 @@
       },
       "RangeFilter": {
         "type": "object",
+        "description": "Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.\n\nA range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.",
         "properties": {
           "field": {
             "allOf": [
               {
                 "$ref": "#/components/schemas/Field"
               }
-            ]
+            ],
+            "description": "The search field.",
+            "example": "validFrom"
           },
           "from": {
+            "description": "The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.",
             "oneOf": [
               {
                 "type": "string",
-                "format": "date-time"
+                "format": "date-time",
+                "example": "2007-01-01T00:00:00Z"
               },
               {
-                "type": "integer"
+                "type": "integer",
+                "example": 1
               },
               {
-                "type": "number"
+                "type": "number",
+                "example": 1
               }
             ]
           },
           "fromInclusive": {
             "type": "boolean",
-            "default": true
+            "default": true,
+            "description": "A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.",
+            "example": true
           },
           "to": {
+            "description": "The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.",
             "oneOf": [
               {
                 "type": "string",
-                "format": "date-time"
+                "format": "date-time",
+                "example": "2007-01-02T00:00:00Z"
               },
               {
-                "type": "integer"
+                "type": "integer",
+                "example": 2
               },
               {
-                "type": "number"
+                "type": "number",
+                "example": 2
               }
             ]
           },
           "toInclusive": {
             "type": "boolean",
-            "default": true
+            "default": true,
+            "description": "A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.",
+            "example": true
           }
         },
         "required": [
@@ -1097,16 +1521,26 @@
       "TermFilter": {
         "type": "object",
         "additionalProperties": false,
+        "description": "Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.",
+        "example": {
+          "field": "id",
+          "operator": "is",
+          "values": [
+            "myId"
+          ]
+        },
         "properties": {
           "field": {
             "allOf": [
               {
                 "$ref": "#/components/schemas/Field"
               }
-            ]
+            ],
+            "description": "The filter field."
           },
           "operator": {
             "type": "string",
+            "description": "The operator used to compare the field's values with the given values.",
             "enum": [
               "is",
               "one_of",
@@ -1116,12 +1550,15 @@
               "greater",
               "not_in",
               "neq"
-            ]
+            ],
+            "example": "is"
           },
           "values": {
             "type": "array",
+            "description": "The filter values.",
             "items": {
-              "type": "string"
+              "type": "string",
+              "example": "myId"
             }
           }
         },
@@ -1133,6 +1570,26 @@
       "FilteredQuery": {
         "type": "object",
         "additionalProperties": false,
+        "description": "Allows to filter the result of a possibly complex query using a possibly complex filter.",
+        "example": {
+          "query": {
+            "textQuery": {
+              "fields": [
+                "couponId"
+              ],
+              "searchPhrase": "disabled"
+            }
+          },
+          "filter": {
+            "termFilter": {
+              "field": "enabled",
+              "operator": "is",
+              "values": [
+                false
+              ]
+            }
+          }
+        },
         "properties": {
           "filter": {
             "$ref": "#/components/schemas/Filter"
@@ -1147,14 +1604,62 @@
         ]
       },
       "MatchAllQuery": {
-        "type": "object"
+        "type": "object",
+        "description": "Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints."
       },
       "NestedQuery": {
         "type": "object",
         "additionalProperties": false,
+        "description": "Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints. \n\nA `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.\n",
+        "example": {
+          "path": "order.shippingAddresses",
+          "query": {
+            "boolQuery": {
+              "must": [
+                {
+                  "boolQuery": {
+                    "must": [
+                      {
+                        "termQuery": {
+                          "fields": [
+                            "order.shippingAddresses.firstName"
+                          ],
+                          "operator": "is",
+                          "values": [
+                            "John"
+                          ]
+                        }
+                      }
+                    ]
+                  }
+                },
+                {
+                  "boolQuery": {
+                    "must": [
+                      {
+                        "termQuery": {
+                          "fields": [
+                            "order.shippingAddresses.lastName"
+                          ],
+                          "operator": "is",
+                          "values": [
+                            "Doe"
+                          ]
+                        }
+                      }
+                    ]
+                  }
+                }
+              ]
+            }
+          },
+          "scoreMode": "avg"
+        },
         "properties": {
           "path": {
             "type": "string",
+            "description": "The path to the nested document.",
+            "example": "order.shippingAddresses",
             "maxLength": 2048
           },
           "query": {
@@ -1162,12 +1667,14 @@
           },
           "scoreMode": {
             "type": "string",
+            "description": "Indicates how scores for matching child objects affect the root parent document’s relevance score.",
             "enum": [
               "avg",
               "total",
               "max",
               "none"
-            ]
+            ],
+            "example": "avg"
           }
         },
         "required": [
@@ -1177,9 +1684,11 @@
       },
       "TermQuery": {
         "type": "object",
+        "description": "A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.\n\n**Limitations:**\n\n* The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.\n* A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.",
         "properties": {
           "fields": {
             "type": "array",
+            "description": "The document fields that the values are matched against, combined with the operator.",
             "items": {
               "$ref": "#/components/schemas/Field"
             },
@@ -1187,6 +1696,7 @@
           },
           "operator": {
             "type": "string",
+            "description": "Returns the operator to use for the term query.",
             "enum": [
               "is",
               "one_of",
@@ -1196,23 +1706,30 @@
               "greater",
               "not_in",
               "neq"
-            ]
+            ],
+            "example": "is"
           },
           "values": {
             "type": "array",
+            "description": "The values that the fields are compared against, combined with the operator.",
             "items": {
+              "example": "myCouponId",
               "oneOf": [
                 {
-                  "type": "string"
+                  "type": "string",
+                  "example": "myCouponId"
                 },
                 {
-                  "type": "number"
+                  "type": "number",
+                  "example": 1
                 },
                 {
-                  "type": "boolean"
+                  "type": "boolean",
+                  "example": true
                 },
                 {
-                  "type": "integer"
+                  "type": "integer",
+                  "example": 1
                 }
               ]
             }
@@ -1226,16 +1743,26 @@
       "TextQuery": {
         "type": "object",
         "additionalProperties": false,
+        "description": "A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.",
+        "example": {
+          "fields": [
+            "couponId"
+          ],
+          "searchPhrase": "limit"
+        },
         "properties": {
           "fields": {
             "type": "array",
+            "description": "The document fields that the search phrase matches against.",
             "items": {
               "$ref": "#/components/schemas/Field"
             },
             "minItems": 1
           },
           "searchPhrase": {
-            "type": "string"
+            "type": "string",
+            "description": "A search phrase, which can include multiple terms separated by spaces.",
+            "example": "campaign summer"
           }
         },
         "required": [
@@ -1246,18 +1773,27 @@
       "Sort": {
         "type": "object",
         "additionalProperties": false,
+        "description": "Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.",
+        "example": {
+          "field": "couponId",
+          "sortOrder": "desc"
+        },
         "properties": {
           "field": {
             "type": "string",
+            "description": "The name of the field to sort on.",
+            "example": "couponId",
             "maxLength": 256
           },
           "sortOrder": {
             "type": "string",
             "default": "asc",
+            "description": "The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.",
             "enum": [
               "asc",
               "desc"
-            ]
+            ],
+            "example": "asc"
           }
         },
         "required": [
@@ -1266,10 +1802,13 @@
       },
       "SearchRequest": {
         "type": "object",
+        "description": "Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.",
         "properties": {
           "limit": {
             "type": "integer",
             "format": "int32",
+            "description": "Maximum records to retrieve per request, not to exceed 200.",
+            "example": 10,
             "maximum": 200,
             "minimum": 1
           },
@@ -1278,6 +1817,7 @@
           },
           "sorts": {
             "type": "array",
+            "description": "The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.",
             "items": {
               "$ref": "#/components/schemas/Sort"
             }
@@ -1296,7 +1836,27 @@
           {
             "$ref": "#/components/schemas/SearchRequest"
           }
-        ]
+        ],
+        "description": "Document representing a search request for retrieving stores within the Admin API. The query is a potentially complex set of expressions.",
+        "example": {
+          "query": {
+            "textQuery": {
+              "fields": [
+                "name",
+                "city"
+              ],
+              "searchPhrase": "downtown"
+            }
+          },
+          "limit": 10,
+          "offset": 0,
+          "sorts": [
+            {
+              "field": "name",
+              "sortOrder": "asc"
+            }
+          ]
+        }
       },
       "PaginatedSearchResult": {
         "additionalProperties": false,
@@ -1305,18 +1865,67 @@
             "$ref": "#/components/schemas/PaginatedResultBase"
           }
         ],
+        "description": "Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.",
+        "example": {
+          "limit": 1,
+          "hits": [
+            {
+              "couponId": "coupon1",
+              "creationDate": "2019-10-20T12:00:00Z",
+              "description": "This coupon is used to give 10% off stuff.",
+              "enabled": false,
+              "exportedCodeCount": 0,
+              "lastModified": "2019-10-30T04:23:59Z",
+              "redemptionCount": 3,
+              "redemptionLimits": {
+                "limitPerCode": 1,
+                "limitPerCustomer": 1,
+                "limitPerTimeFrame": {
+                  "limit": 2,
+                  "redemptionTimeFrame": 24
+                }
+              },
+              "singleCode": "MyCode",
+              "systemCodesConfig": {
+                "codePrefix": "SG",
+                "numberOfCodes": 500000
+              },
+              "totalCodesCount": 50,
+              "type": "single_code"
+            }
+          ],
+          "query": {
+            "textQuery": {
+              "fields": [
+                "id",
+                "description"
+              ],
+              "searchPhrase": "stuff"
+            }
+          },
+          "sorts": [
+            {
+              "field": "couponId",
+              "sortOrder": "desc"
+            }
+          ],
+          "offset": 2,
+          "total": 8
+        },
         "properties": {
           "query": {
             "$ref": "#/components/schemas/Query"
           },
           "sorts": {
             "type": "array",
+            "description": "The sorting that was applied to the result.",
             "items": {
               "$ref": "#/components/schemas/Sort"
             }
           },
           "hits": {
             "type": "array",
+            "description": "The sorted array of search hits. Can be empty.",
             "items": {
               "type": "object"
             }
@@ -1332,9 +1941,11 @@
             "$ref": "#/components/schemas/PaginatedSearchResult"
           }
         ],
+        "description": "Document representing a store search result. This includes the query, sorts, hits (array of Store objects), and pagination information.",
         "properties": {
           "hits": {
             "type": "array",
+            "description": "The sorted array of search hits (Store objects). Can be empty.",
             "items": {
               "$ref": "#/components/schemas/Store"
             }
@@ -1353,6 +1964,11 @@
           "application/problem+json": {
             "schema": {
               "$ref": "#/components/schemas/ErrorResponse"
+            },
+            "examples": {
+              "UnauthorizedExample": {
+                "$ref": "#/components/examples/UnauthorizedExample"
+              }
             }
           }
         }
@@ -1363,6 +1979,11 @@
           "application/problem+json": {
             "schema": {
               "$ref": "#/components/schemas/ErrorResponse"
+            },
+            "examples": {
+              "ForbiddenExample": {
+                "$ref": "#/components/examples/ForbiddenExample"
+              }
             }
           }
         }
@@ -1372,21 +1993,29 @@
       "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"
       },
       "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"
+          }
         }
       },
       "select": {
@@ -1397,12 +2026,428 @@
         "explode": true,
         "schema": {
           "$ref": "#/components/schemas/Select"
+        },
+        "examples": {
+          "select": {
+            "value": "(**)"
+          }
+        }
+      }
+    },
+    "examples": {
+      "StoreResultSuccess": {
+        "summary": "Successful store list result",
+        "description": "Example response for a successful get stores request with pagination",
+        "value": {
+          "limit": 2,
+          "offset": 0,
+          "total": 5,
+          "data": [
+            {
+              "id": "store-001",
+              "name": "Downtown Store",
+              "address1": "123 Main St",
+              "address2": "Suite 100",
+              "city": "San Francisco",
+              "stateCode": "CA",
+              "postalCode": "94102",
+              "countryCode": "US",
+              "phone": "+1-555-123-4567",
+              "email": "downtown@example.com",
+              "latitude": 37.7749,
+              "longitude": -122.4194,
+              "inventoryId": "inventory-001",
+              "storeHours": {
+                "default": {
+                  "markup": "08:00 am - 07:30 pm",
+                  "source": "08:00 am - 07:30 pm"
+                }
+              },
+              "storeEvents": {
+                "default": {
+                  "markup": "Sale 40% off",
+                  "source": "Sale 40% off"
+                }
+              },
+              "storeLocatorEnabled": true,
+              "posEnabled": true,
+              "creationDate": "2023-01-15T10:30:00.000Z",
+              "lastModified": "2024-06-20T14:45:00.000Z",
+              "c_customAttribute": "Custom Value"
+            },
+            {
+              "id": "store-002",
+              "name": "Downtown Plaza",
+              "address1": "456 Market St",
+              "city": "San Francisco",
+              "stateCode": "CA",
+              "postalCode": "94103",
+              "countryCode": "US",
+              "phone": "+1-555-234-5678",
+              "email": "plaza@example.com",
+              "latitude": 37.7833,
+              "longitude": -122.4167,
+              "inventoryId": "inventory-002",
+              "storeHours": {
+                "default": {
+                  "markup": "08:00 am - 07:30 pm",
+                  "source": "08:00 am - 07:30 pm"
+                }
+              },
+              "storeLocatorEnabled": true,
+              "posEnabled": false,
+              "creationDate": "2023-03-20T08:15:00.000Z",
+              "lastModified": "2024-07-10T16:20:00.000Z"
+            }
+          ]
+        }
+      },
+      "UnauthorizedExample": {
+        "value": {
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
+          "title": "Unauthorized",
+          "detail": "Your access token is invalid or expired and can’t be used to identify a user."
+        }
+      },
+      "ForbiddenExample": {
+        "value": {
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
+          "title": "Forbidden",
+          "detail": "Your access token is valid, but you don’t have the required permissions to access the resource."
+        }
+      },
+      "StoreSuccess": {
+        "summary": "Successful single store retrieval",
+        "description": "Example response for a successful get store by ID request",
+        "value": {
+          "id": "store-001",
+          "name": "Downtown Store",
+          "address1": "123 Main St",
+          "address2": "Suite 100",
+          "city": "San Francisco",
+          "stateCode": "CA",
+          "postalCode": "94102",
+          "countryCode": "US",
+          "phone": "+1-555-123-4567",
+          "fax": "+1-555-123-4568",
+          "email": "downtown@example.com",
+          "latitude": 37.7749,
+          "longitude": -122.4194,
+          "inventoryId": "inventory-001",
+          "storeHours": {
+            "default": {
+              "markup": "08:00 am - 07:30 pm",
+              "source": "08:00 am - 07:30 pm"
+            }
+          },
+          "storeEvents": {
+            "default": {
+              "markup": "Sale 40% off",
+              "source": "Sale 40% off"
+            }
+          },
+          "image": {
+            "path": "https://example.com/images/store-001.jpg"
+          },
+          "storeLocatorEnabled": true,
+          "posEnabled": true,
+          "creationDate": "2023-01-15T10:30:00.000Z",
+          "lastModified": "2024-06-20T14:45:00.000Z",
+          "c_customAttribute": "Custom Value",
+          "c_region": "West Coast"
+        }
+      },
+      "StoreNotFound": {
+        "summary": "Store Not Found",
+        "description": "Example error response when the requested store ID does not exist",
+        "value": {
+          "title": "Store Not Found",
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/store-not-found",
+          "detail": "No store with ID 'store-999' could be found."
+        }
+      },
+      "CreateStore": {
+        "summary": "Create a new store",
+        "description": "Example request body to create a new store via PUT",
+        "value": {
+          "id": "new-store-001",
+          "name": "New Downtown Store",
+          "address1": "789 Market St",
+          "city": "San Francisco",
+          "stateCode": "CA",
+          "postalCode": "94103",
+          "countryCode": "US",
+          "phone": "+1-555-789-0123",
+          "email": "newstore@example.com",
+          "latitude": 37.785,
+          "longitude": -122.41,
+          "storeLocatorEnabled": true,
+          "posEnabled": false
+        }
+      },
+      "ReplaceStoreSuccess": {
+        "summary": "Successful store replacement",
+        "description": "Example response for a successful PUT store replacement (200)",
+        "value": {
+          "id": "store-001",
+          "name": "Replaced Downtown Store",
+          "address1": "789 Market St",
+          "city": "San Francisco",
+          "stateCode": "CA",
+          "postalCode": "94103",
+          "countryCode": "US",
+          "phone": "+1-555-789-0123",
+          "email": "replaced@example.com",
+          "latitude": 37.785,
+          "longitude": -122.41,
+          "storeLocatorEnabled": true,
+          "posEnabled": true,
+          "creationDate": "2023-01-15T10:30:00.000Z",
+          "lastModified": "2026-04-01T12:00:00.000Z"
+        }
+      },
+      "CreateStoreSuccess": {
+        "summary": "Successful store creation",
+        "description": "Example response for a successful PUT store creation (201)",
+        "value": {
+          "id": "new-store-001",
+          "name": "New Downtown Store",
+          "address1": "789 Market St",
+          "city": "San Francisco",
+          "stateCode": "CA",
+          "postalCode": "94103",
+          "countryCode": "US",
+          "phone": "+1-555-789-0123",
+          "email": "newstore@example.com",
+          "latitude": 37.785,
+          "longitude": -122.41,
+          "storeLocatorEnabled": true,
+          "posEnabled": false,
+          "creationDate": "2026-04-01T10:00:00.000Z",
+          "lastModified": "2026-04-01T10:00:00.000Z"
+        }
+      },
+      "IdConflict": {
+        "summary": "ID Conflict",
+        "description": "Example error response when the store ID in the path does not match the ID in the request body",
+        "value": {
+          "title": "ID Conflict",
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/id-conflict",
+          "detail": "The ID in the URL 'store-001' does not match the ID in the body 'store-002'."
+        }
+      },
+      "UpdateStore": {
+        "summary": "Update an existing store",
+        "description": "Example request body to update an existing store via PATCH",
+        "value": {
+          "id": "store-001",
+          "name": "Updated Downtown Store",
+          "phone": "+1-555-123-9999",
+          "email": "updated@example.com",
+          "address2": "Suite 200"
+        }
+      },
+      "UpdateStoreSuccess": {
+        "summary": "Successful store update",
+        "description": "Example response for a successful PATCH store update",
+        "value": {
+          "id": "store-001",
+          "name": "Updated Downtown Store",
+          "address1": "123 Main St",
+          "address2": "Suite 200",
+          "city": "San Francisco",
+          "stateCode": "CA",
+          "postalCode": "94102",
+          "countryCode": "US",
+          "phone": "+1-555-123-9999",
+          "fax": "+1-555-123-4568",
+          "email": "updated@example.com",
+          "latitude": 37.7749,
+          "longitude": -122.4194,
+          "inventoryId": "inventory-001",
+          "storeLocatorEnabled": true,
+          "posEnabled": true,
+          "creationDate": "2023-01-15T10:30:00.000Z",
+          "lastModified": "2026-04-01T11:00:00.000Z"
+        }
+      },
+      "StoreSearchByName": {
+        "summary": "Search stores by name",
+        "description": "Example request to search for stores by name using a text query",
+        "value": {
+          "query": {
+            "textQuery": {
+              "fields": [
+                "name"
+              ],
+              "searchPhrase": "downtown"
+            }
+          },
+          "limit": 10,
+          "offset": 0,
+          "sorts": [
+            {
+              "field": "name",
+              "sortOrder": "asc"
+            }
+          ]
+        }
+      },
+      "StoreSearchByCity": {
+        "summary": "Search stores by city and state",
+        "description": "Example request to search for stores in a specific city and state using term queries",
+        "value": {
+          "query": {
+            "boolQuery": {
+              "must": [
+                {
+                  "termQuery": {
+                    "fields": [
+                      "city"
+                    ],
+                    "operator": "is",
+                    "values": [
+                      "San Francisco"
+                    ]
+                  }
+                },
+                {
+                  "termQuery": {
+                    "fields": [
+                      "stateCode"
+                    ],
+                    "operator": "is",
+                    "values": [
+                      "CA"
+                    ]
+                  }
+                }
+              ]
+            }
+          },
+          "limit": 25,
+          "offset": 0,
+          "sorts": [
+            {
+              "field": "name",
+              "sortOrder": "asc"
+            }
+          ]
+        }
+      },
+      "StoreSearchResultSuccess": {
+        "summary": "Successful store search result",
+        "description": "Example response for a successful store search with multiple results",
+        "value": {
+          "limit": 2,
+          "offset": 0,
+          "total": 10,
+          "query": {
+            "textQuery": {
+              "fields": [
+                "name"
+              ],
+              "searchPhrase": "downtown"
+            }
+          },
+          "sorts": [
+            {
+              "field": "name",
+              "sortOrder": "asc"
+            }
+          ],
+          "hits": [
+            {
+              "id": "store-001",
+              "name": "Downtown Store",
+              "address1": "123 Main St",
+              "address2": "Suite 100",
+              "city": "San Francisco",
+              "stateCode": "CA",
+              "postalCode": "94102",
+              "countryCode": "US",
+              "phone": "+1-555-123-4567",
+              "email": "downtown@example.com",
+              "latitude": 37.7749,
+              "longitude": -122.4194,
+              "inventoryId": "inventory-001",
+              "storeHours": {
+                "default": {
+                  "markup": "08:00 am - 07:30 pm",
+                  "source": "08:00 am - 07:30 pm"
+                }
+              },
+              "storeEvents": {
+                "default": {
+                  "markup": "Sale 40% off",
+                  "source": "Sale 40% off"
+                }
+              },
+              "storeLocatorEnabled": true,
+              "posEnabled": true,
+              "creationDate": "2023-01-15T10:30:00.000Z",
+              "lastModified": "2024-06-20T14:45:00.000Z",
+              "c_customAttribute": "Custom Value"
+            },
+            {
+              "id": "store-002",
+              "name": "Downtown Plaza",
+              "address1": "456 Market St",
+              "city": "San Francisco",
+              "stateCode": "CA",
+              "postalCode": "94103",
+              "countryCode": "US",
+              "phone": "+1-555-234-5678",
+              "email": "plaza@example.com",
+              "latitude": 37.7833,
+              "longitude": -122.4167,
+              "inventoryId": "inventory-002",
+              "storeHours": {
+                "default": {
+                  "markup": "Mon-Sun: 10am-8pm",
+                  "source": "Mon-Sun: 10am-8pm"
+                }
+              },
+              "storeLocatorEnabled": true,
+              "posEnabled": false,
+              "creationDate": "2023-03-20T08:15:00.000Z",
+              "lastModified": "2024-07-10T16:20:00.000Z"
+            }
+          ]
+        }
+      },
+      "MalformedSearchParameter": {
+        "summary": "Malformed search query",
+        "description": "Example error response when the search query is malformed",
+        "value": {
+          "title": "Bad Request",
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
+          "detail": "The search query is malformed. Please check the query syntax."
+        }
+      },
+      "InvalidQueryField": {
+        "summary": "Unqueryable Field",
+        "description": "Example error response when an invalid field is used in the query",
+        "value": {
+          "title": "Unqueryable Field",
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unqueryable-field",
+          "detail": "Invalid field 'invalidField' in query. Please use a valid searchable field."
+        }
+      },
+      "FieldNotSortable": {
+        "summary": "Field Not Sortable",
+        "description": "Example error response when an invalid field is used in the query",
+        "value": {
+          "title": "Field Not Sortable",
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/field-not-sortable",
+          "detail": "The field 'invalidField' can't be used to sort the results."
         }
       }
     },
     "securitySchemes": {
       "AmOAuth2": {
         "type": "oauth2",
+        "description": "OAuth 2.0 Authorization via Account Manager",
         "flows": {
           "clientCredentials": {
             "tokenUrl": "https://account.demandware.com/dw/oauth2/access_token",