@salesforce/b2c-tooling-sdk 2.4.0 → 2.5.0

package/node_modules/@salesforce/b2c-api-schemas/scapi/pricing/shopper-promotions/v1.json

@@ -2,7 +2,8 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Shopper Promotions",
-    "version": "1.4.0",
+    "description": "[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-promotions/shopper-promotions-oas-v1-public.yaml)\n\n# API Overview\n\nRetrieve information about active promotions within the context of a shopper and a site. You can use this API to retrieve promotions that you configured in the commerce platform by searching for specific promotion IDs or by searching for promotions associated with a campaign.\n\n## Authentication & Authorization\n\nThe Shopper Promotions API requires a JSON Web Token acquired via the Shopper Customers endpoint:\n\n```\nhttps://{shortCode}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/{organizationId}/customers/actions/login\n```\n\nYou must include the relevant scope(s) in the client ID used to generate the SLAS token. For details, see [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)\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 this 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### Get Promotions by ID\n\nRetrieve one or more promotions by their IDs (comma-separated, max 50).\n\n```sh\ncurl \"https://{shortCode}.api.commercecloud.salesforce.com/pricing/shopper-promotions/v1/organizations/{organizationId}/promotions?ids=Buy5for50,free_shipping&siteId=RefArch\" \\\n  -H \"Authorization: Bearer {access_token}\"\n```\n\n\n### Get Promotion by Promotion ID\n\nUse the Shopper Promotions API to find promotion information by the promotion ID.\n\nFor example, a customer who is browsing on a commerce shopping app built using Commerce Cloud APIs can see the details about the applied promotions in the cart.\n\n### Get Promotion by Campaign ID\n\nUse the Shopper Promotions API to find promotion information by the campaign ID.\n\nFor example, a customer who is browsing on a commerce shopping app built using Commerce Cloud APIs can see the possible promotions that can be applied in the cart.\n\n## Related APIs\n\n- [Promotions (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions?meta=Summary) — Create and manage promotions, discounts, and qualifiers.",
+    "version": "1.4.2",
     "x-api-type": "Shopper",
     "x-api-family": "Pricing"
   },
@@ -11,6 +12,7 @@
       "url": "https://{shortCode}.api.commercecloud.salesforce.com/pricing/shopper-promotions/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,31 +21,42 @@
   "paths": {
     "/organizations/{organizationId}/promotions": {
       "get": {
+        "summary": "Return an array of enabled promotions for specified IDs.",
+        "description": "In the request URL, you can specify up to 50 IDs. If you specify an ID that contains either parentheses or the separator characters, you must URL encode these characters. \nEach request returns only enabled promotions as the server does not consider promotion qualifiers or schedules.",
         "operationId": "getPromotions",
         "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": "ids",
             "in": "query",
+            "description": "A comma-separated list of promotion identifiers. Maximum: 50.",
             "required": true,
             "style": "form",
             "explode": true,
@@ -58,16 +71,26 @@
           {
             "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": "personalized",
             "in": "query",
+            "description": "Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.\n\nWhen set to `none`, the server skips applying personalization to the response.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -75,37 +98,27 @@
               "type": "string",
               "enum": [
                 "none"
-              ]
+              ],
+              "example": "none"
             }
           },
           {
             "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": "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,
@@ -121,6 +134,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/PromotionResult"
+                },
+                "examples": {
+                  "PromotionsResult": {
+                    "$ref": "#/components/examples/PromotionsResult"
+                  }
                 }
               }
             }
@@ -131,6 +149,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "getPromotions404": {
+                    "$ref": "#/components/examples/PromotionsNotFound404"
+                  }
                 }
               }
             }
@@ -154,11 +177,14 @@
     },
     "/organizations/{organizationId}/promotions/campaigns/{campaignId}": {
       "get": {
+        "summary": "Return an array of enabled promotions matching the specified filter criteria.",
+        "description": "Retrieves promotion information using filter criteria. In the request URL, you must provide a campaign_id parameter, and you can optionally specify a date\nrange by providing start_date and end_date parameters. Both parameters are required to specify a date range, and\nomitting one causes the server to return a MissingParameterException fault. Each request returns only enabled\npromotions, since the server does not consider promotion qualifiers or schedules.",
         "operationId": "getPromotionsForCampaign",
         "parameters": [
           {
             "name": "campaignId",
             "in": "path",
+            "description": "Find the promotions assigned to this campaign (mandatory).",
             "required": true,
             "style": "simple",
             "explode": false,
@@ -171,26 +197,35 @@
           {
             "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": "startDate",
             "in": "query",
+            "description": "The start date of the promotion in ISO 8601 date time format.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -201,6 +236,7 @@
           {
             "name": "endDate",
             "in": "query",
+            "description": "The end date of the promotion in ISO 8601 date time format.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -211,6 +247,7 @@
           {
             "name": "currency",
             "in": "query",
+            "description": "The currency mnemonic specified for price. This parameter is effective only for product suggestions.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -221,6 +258,7 @@
           {
             "name": "personalized",
             "in": "query",
+            "description": "Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.\n\nWhen set to `none`, the server skips applying personalization to the response.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -228,37 +266,27 @@
               "type": "string",
               "enum": [
                 "none"
-              ]
+              ],
+              "example": "none"
             }
           },
           {
             "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": "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,
@@ -274,6 +302,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/PromotionResult"
+                },
+                "examples": {
+                  "PromotionsResult": {
+                    "$ref": "#/components/examples/PromotionsResult"
+                  }
                 }
               }
             }
@@ -284,6 +317,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "getPromotionsForCampaign400": {
+                    "$ref": "#/components/examples/InvalidDate400"
+                  }
                 }
               }
             }
@@ -294,6 +332,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "getPromotions404": {
+                    "$ref": "#/components/examples/PromotionsNotFound404"
+                  }
                 }
               }
             }
@@ -320,27 +363,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"
@@ -357,14 +411,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"
@@ -377,33 +436,53 @@
       },
       "Promotion": {
         "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 promotion.",
         "properties": {
           "calloutMsg": {
-            "type": "string"
+            "type": "string",
+            "description": "The localized call-out message of the promotion.",
+            "example": "$30 Fixed Shipping Amount Above 150"
           },
           "currency": {
-            "type": "string"
+            "type": "string",
+            "description": "The currency that a promotion can be applied to. A null value means that the promotion applies to all allowed\n currencies.",
+            "example": "USD"
           },
           "details": {
-            "type": "string"
+            "type": "string",
+            "description": "The localized detailed description of the promotion.",
+            "example": "$30 Fixed Shipping Amount Above 150"
           },
           "endDate": {
             "type": "string",
-            "format": "date-time"
+            "format": "date-time",
+            "description": "The end date of the promotion. This property follows the ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ . The time\n zone of the date time is always UTC.",
+            "example": "2015-07-04T21:00:00Z"
           },
           "id": {
-            "type": "string"
+            "type": "string",
+            "description": "The unique ID of the promotion.",
+            "example": "$30FixedShippingAmountAbove150"
           },
           "image": {
-            "type": "string"
+            "type": "string",
+            "description": "The URL to the promotion image."
           },
           "name": {
-            "type": "string"
+            "type": "string",
+            "description": "The localized name of the promotion.",
+            "example": "$30 Fixed Shipping Amount Above 150"
           },
           "startDate": {
             "type": "string",
-            "format": "date-time"
+            "format": "date-time",
+            "description": "The start date of the promotion. This property follows the ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ. The\n time zone of the date time is always UTC.",
+            "example": "2015-07-04T21:00:00Z"
           }
         },
         "required": [
@@ -417,9 +496,29 @@
             "$ref": "#/components/schemas/ResultBase"
           }
         ],
+        "description": "Result document containing an array of promotions.",
+        "example": {
+          "limit": 2,
+          "data": [
+            {
+              "calloutMsg": "Buy5for50",
+              "details": "Buy5for50",
+              "id": "Buy5for50",
+              "name": "Buy5for50"
+            },
+            {
+              "calloutMsg": "$5 off Men's Ties",
+              "details": "$5 off Men's Ties (with coupon)",
+              "id": "$5_off_ties_promotion",
+              "name": "5 Off Ties Promotion"
+            }
+          ],
+          "total": 2
+        },
         "properties": {
           "data": {
             "type": "array",
+            "description": "The array of promotion documents.",
             "items": {
               "$ref": "#/components/schemas/Promotion"
             }
@@ -435,17 +534,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
           }
         },
@@ -457,6 +564,8 @@
       },
       "CurrencyCode": {
         "type": "string",
+        "description": "A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.",
+        "example": "USD",
         "pattern": "^([A-Z][A-Z][A-Z]|N/A)$"
       }
     },
@@ -464,26 +573,35 @@
       "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"
+          }
         }
       },
       "ids": {
         "name": "ids",
         "in": "query",
+        "description": "A comma-separated list of promotion identifiers. Maximum: 50.",
         "required": true,
         "style": "form",
         "explode": true,
@@ -498,16 +616,26 @@
       "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"
+          }
         }
       },
       "personalized": {
         "name": "personalized",
         "in": "query",
+        "description": "Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.\n\nWhen set to `none`, the server skips applying personalization to the response.",
         "required": false,
         "style": "form",
         "explode": true,
@@ -515,12 +643,14 @@
           "type": "string",
           "enum": [
             "none"
-          ]
+          ],
+          "example": "none"
         }
       },
       "campaignId": {
         "name": "campaignId",
         "in": "path",
+        "description": "Find the promotions assigned to this campaign (mandatory).",
         "required": true,
         "style": "simple",
         "explode": false,
@@ -533,6 +663,7 @@
       "startDate": {
         "name": "startDate",
         "in": "query",
+        "description": "The start date of the promotion in ISO 8601 date time format.",
         "required": false,
         "style": "form",
         "explode": true,
@@ -543,6 +674,7 @@
       "endDate": {
         "name": "endDate",
         "in": "query",
+        "description": "The end date of the promotion in ISO 8601 date time format.",
         "required": false,
         "style": "form",
         "explode": true,
@@ -553,6 +685,7 @@
       "currency": {
         "name": "currency",
         "in": "query",
+        "description": "The currency mnemonic specified for price. This parameter is effective only for product suggestions.",
         "required": false,
         "style": "form",
         "explode": true,
@@ -563,31 +696,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"
         }
       },
       "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,
@@ -596,9 +718,56 @@
         }
       }
     },
+    "examples": {
+      "PromotionsResult": {
+        "summary": "Multiple promotions retrieved by ID",
+        "value": {
+          "limit": 2,
+          "data": [
+            {
+              "id": "Buy5for50",
+              "name": "Buy 5 for $50",
+              "calloutMsg": "Buy 5 for $50",
+              "details": "Buy any 5 qualifying items and pay only $50. Discount applied at checkout.",
+              "currency": "USD",
+              "startDate": "2025-01-01T00:00:00Z",
+              "endDate": "2025-12-31T23:59:00Z"
+            },
+            {
+              "id": "$5_off_ties_promotion",
+              "name": "$5 Off Ties Promotion",
+              "calloutMsg": "$5 off Men's Ties",
+              "details": "$5 off Men's Ties when you apply coupon code TIES5.",
+              "currency": "USD",
+              "startDate": "2025-03-01T00:00:00Z",
+              "endDate": "2025-06-30T23:59:00Z",
+              "c_promoCategory": "apparel"
+            }
+          ],
+          "total": 2
+        }
+      },
+      "PromotionsNotFound404": {
+        "value": {
+          "type": "/PromotionNotFoundException",
+          "detail": "There is no promotion found with the given ID for the requested site.",
+          "title": "Not Found",
+          "instance": "/foo"
+        }
+      },
+      "InvalidDate400": {
+        "value": {
+          "type": "/InvalidDateException",
+          "detail": "Invalid Start or End Date",
+          "title": "Invalid Start or End Date",
+          "instance": "/foo"
+        }
+      }
+    },
     "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",
@@ -617,6 +786,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",