@salesforce/b2c-tooling-sdk 2.3.0 → 2.5.0

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

@@ -2,7 +2,8 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Shopper Consents",
-    "version": "1.2.0",
+    "description": "[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-consents/shopper-consents-oas-v1-public.yaml)\n\n# API Overview\n\nThe Shopper Consent API offers a centralized method for managing shopper consent. With this API, shoppers can view and update subscription preferences for marketing communications across various channels. This API controls how and where shoppers receive marketing messages while ensuring compliance with privacy regulations.\n\nThe Shopper Consent API provides sensible defaults for optional fields to simplify integration:\n- Consent Type: Defaults to \"marketing\" for marketing communications.\n- Consent Required: Defaults to false, making subscriptions optional by default.\n- Default Status: Defaults to \"opt_out\" to respect privacy-first principles.\n- Tags: Defaults to an empty array when not specified.\n\n## Authentication & Authorization\n\nThe Shopper Consent API requires a shopper access token from the Shopper Login and API Access Service (SLAS).\n\nYou must include the relevant scope(s) in the client ID used to generate the SLAS token.\n\n- `sfcc.shopper-consents`: Required for reading communication subscription data (GET operations).\n- `sfcc.shopper-consents.rw`: Required for creating and modifying communication subscription consent data (POST operations).\n\nFor a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)\n\nFor details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) in the SLAS guides.\n\n## Response Details\n\n### Personalization\n\nResponses from this API are not personalized via the Shopper Context API.\n\n### Caching\n\nResponses from this API are not cached. Consent data is unique to each shopper.\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 Consent Subscriptions\n\nRetrieve the communication subscriptions for a shopper.\n\n```sh\ncurl \"https://{shortCode}.api.commercecloud.salesforce.com/shopper/shopper-consents/v1/organizations/{organizationId}/subscriptions?siteId=RefArch\" \\\n  -H \"Authorization: Bearer {access_token}\"\n```\n\n\n### Retrieve communication subscriptions\n\nRetrieve relevant communication subscription options with rich display information.\n    - Communication subscription options can be filtered by one or more qualifying tags.\n    - Use the `expand` parameter to conditionally include subscription status.\n\n### Update individual subscription consent\n\nUpdate consent status for a single subscription with simple request/response pattern.\n\n### Bulk subscription updates\n\nEfficiently manage multiple subscription preferences with a single request.\n    - Update 1-50 subscriptions per bulk request.\n    - Partial success handling with detailed error reporting for failed updates.\n\n## Data Model\n\n### Subscriptions\nSubscriptions represent a shopper's consent to receive specific types of marketing communications. Each subscription includes:\n\n- Subscription Id: Descriptive identifier\n- Channels: Array of communication methods - Email, SMS, or WhatsApp\n- Consent Type: Marketing or legal subscription classification\n- Consent Required: Whether the subscription is mandatory for the shopper\n- Default Status: Default opt-in or opt-out behavior\n- Consent Status: Array of status entries for each channel showing current opt-in or opt-out status (conditionally returned based on expand parameter)\n- Rich Display Information: \n  - Title: Simple localized string for subscription name\n  - Subtitle: Simple localized string with HTML markup support for descriptions\n  - Localized content determined by the locale parameter\n- Tags: Categorical tags indicating where the subscription option can appear (defaults to empty array, max 10 tags)\n\n### Channels\nChannels define the communication methods available for a subscription:\n- `email`: Email communications\n- `sms`: SMS/text messages\n- `whatsapp`: WhatsApp messaging\n\n### Tags\nTags indicate where subscription options are displayed in your shopper experience. Tags are also accepted as optional filtering parameters in the retrieval of shopper consent subscriptions. For example:\n- `homepage_banner`: Main website homepage\n- `registration`: Shopper registration form\n- `checkout`: Checkout flow\n- `user_profile`: User profile management section\n\n## Advanced Features\n\n### Expand Parameter\n\nThe `expand` parameter provides conditional field inclusion:\n- `expand=[]` (default): Returns basic subscription information\n- `expand=[\"consentStatus\"]`: Include consent status information in the response\n- Future expansion may include additional fields\n\n## Best Practices\n\n- Use single subscription updates for real-time, interactive preference changes.\n- Use bulk operations when updating multiple subscriptions to reduce API calls and improve performance.\n- Only request status information when needed using the expand parameter to reduce latency.",
+    "version": "1.2.2",
     "x-api-type": "Shopper",
     "x-api-family": "Shopper"
   },
@@ -11,6 +12,7 @@
       "url": "https://{shortCode}.api.commercecloud.salesforce.com/shopper/shopper-consents/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,41 +21,61 @@
   "paths": {
     "/organizations/{organizationId}/subscriptions": {
       "get": {
+        "summary": "Get shopper consent preferences",
+        "description": "Retrieve all subscription preferences for the shopper (authenticated or guest).\n\nUse the 'expand' parameter to include additional fields in the response:\n- expand=[\"consentStatus\"]: Include subscription status information\n- expand=[]: Default behavior, excludes status for privacy and performance\n\nThe expand parameter provides privacy benefits by not exposing sensitive status \ninformation unless explicitly requested.\n",
         "operationId": "getSubscriptions",
         "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": "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": "tags",
             "in": "query",
+            "description": "Optional parameter of 0 or more query string values which act as a filtering criteria. Multiple values are treated with `OR` logic, and absence of a value indicates no filtering by tag is desired.",
             "required": false,
             "style": "form",
             "explode": false,
@@ -64,11 +86,29 @@
               },
               "maxItems": 10,
               "minItems": 0
+            },
+            "examples": {
+              "one": {
+                "summary": "One tag filter",
+                "value": [
+                  "homepage_banner"
+                ]
+              },
+              "multiple": {
+                "summary": "Multiple tag filters (ORs)",
+                "value": [
+                  "homepage_banner",
+                  "user_profile",
+                  "checkout",
+                  "registration"
+                ]
+              }
             }
           },
           {
             "name": "expand",
             "in": "query",
+            "description": "Optional parameter to expand response with additional fields. \nAccepts an array of field names to include in the response.\nCurrently supports:\n- \"consentStatus\": Include consent status information in the response\n\nFuture expansions may include additional fields.\n",
             "required": false,
             "style": "form",
             "explode": false,
@@ -79,41 +119,43 @@
                 "type": "string",
                 "enum": [
                   "consentStatus"
-                ]
+                ],
+                "example": "consentStatus"
               },
               "maxItems": 10,
               "minItems": 0,
               "uniqueItems": true
+            },
+            "examples": {
+              "empty": {
+                "summary": "No expansion (default behavior)",
+                "value": []
+              },
+              "consentStatus": {
+                "summary": "Include status information",
+                "value": [
+                  "consentStatus"
+                ]
+              }
             }
           },
           {
             "name": "sfdc_usid",
             "in": "header",
+            "description": "A unique shopper identifier (USID) for tracking client context.\nUsed with endpoints secured with ShopperClientContextToken.\nThis header is required for all endpoints secured with ShopperClientContextToken.",
             "required": false,
             "style": "simple",
             "explode": false,
             "schema": {
               "type": "string",
-              "format": "uuid"
-            }
-          },
-          {
-            "name": "sfdc_dw_dnt",
-            "in": "header",
-            "required": false,
-            "style": "simple",
-            "explode": false,
-            "schema": {
-              "type": "string",
-              "enum": [
-                "0",
-                "1"
-              ]
+              "format": "uuid",
+              "example": "550e8400-e29b-41d4-a716-446655440000"
             }
           },
           {
             "name": "personalized",
             "in": "query",
+            "description": "Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -121,12 +163,14 @@
               "type": "string",
               "enum": [
                 "none"
-              ]
+              ],
+              "example": "none"
             }
           },
           {
             "name": "sfdc_shopper_context",
             "in": "header",
+            "description": "Shopper context information (for example clientIP, sourceCode, and customQualifiers)\npassed in from a trusted backend application.",
             "required": false,
             "style": "simple",
             "explode": false,
@@ -142,6 +186,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ConsentSubscriptionResponse"
+                },
+                "examples": {
+                  "ConsentSubscriptionResponseAuthenticated": {
+                    "$ref": "#/components/examples/ConsentSubscriptionResponseAuthenticated"
+                  },
+                  "ConsentSubscriptionResponseAuthenticatedExpanded": {
+                    "$ref": "#/components/examples/ConsentSubscriptionResponseAuthenticatedExpanded"
+                  },
+                  "ConsentSubscriptionResponseGuest": {
+                    "$ref": "#/components/examples/ConsentSubscriptionResponseGuest"
+                  }
                 }
               }
             }
@@ -152,6 +207,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "ConsentSubscriptionError": {
+                    "$ref": "#/components/examples/ConsentSubscriptionError"
+                  }
                 }
               }
             }
@@ -173,66 +233,74 @@
         ]
       },
       "post": {
+        "summary": "Update shopper subscription preference",
+        "description": "Update the consent status for a single subscription.",
         "operationId": "updateSubscription",
         "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": "locale",
             "in": "query",
+            "description": "A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.",
             "required": false,
             "style": "form",
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/LocaleCode"
+            },
+            "examples": {
+              "LanguageCountry": {
+                "value": "en-US"
+              },
+              "CountryCode": {
+                "value": "US"
+              }
             }
           },
           {
             "name": "sfdc_usid",
             "in": "header",
+            "description": "A unique shopper identifier (USID) for tracking client context.\nUsed with endpoints secured with ShopperClientContextToken.\nThis header is required for all endpoints secured with ShopperClientContextToken.",
             "required": false,
             "style": "simple",
             "explode": false,
             "schema": {
               "type": "string",
-              "format": "uuid"
-            }
-          },
-          {
-            "name": "sfdc_dw_dnt",
-            "in": "header",
-            "required": false,
-            "style": "simple",
-            "explode": false,
-            "schema": {
-              "type": "string",
-              "enum": [
-                "0",
-                "1"
-              ]
+              "format": "uuid",
+              "example": "550e8400-e29b-41d4-a716-446655440000"
             }
           },
           {
             "name": "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,
@@ -246,6 +314,11 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ConsentSubscriptionRequest"
+              },
+              "examples": {
+                "ConsentSubscriptionUpdateRequest": {
+                  "$ref": "#/components/examples/ConsentSubscriptionUpdateRequest"
+                }
               }
             }
           },
@@ -258,6 +331,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ConsentSubscriptionUpdateResponse"
+                },
+                "examples": {
+                  "ConsentSubscriptionUpdateResponseSuccess": {
+                    "$ref": "#/components/examples/ConsentSubscriptionUpdateResponseSuccess"
+                  }
                 }
               }
             }
@@ -268,6 +346,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "ConsentSubscriptionUpdateError": {
+                    "$ref": "#/components/examples/ConsentSubscriptionUpdateError"
+                  }
                 }
               }
             }
@@ -289,66 +372,74 @@
     },
     "/organizations/{organizationId}/subscriptions/actions/bulk": {
       "post": {
+        "summary": "Update shopper subscription preferences",
+        "description": "Update the consent status for multiple subscriptions in a single bulk request. Supports 1-50 subscription updates per request with partial success handling.",
         "operationId": "updateSubscriptions",
         "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": "locale",
             "in": "query",
+            "description": "A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.",
             "required": false,
             "style": "form",
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/LocaleCode"
+            },
+            "examples": {
+              "LanguageCountry": {
+                "value": "en-US"
+              },
+              "CountryCode": {
+                "value": "US"
+              }
             }
           },
           {
             "name": "sfdc_usid",
             "in": "header",
+            "description": "A unique shopper identifier (USID) for tracking client context.\nUsed with endpoints secured with ShopperClientContextToken.\nThis header is required for all endpoints secured with ShopperClientContextToken.",
             "required": false,
             "style": "simple",
             "explode": false,
             "schema": {
               "type": "string",
-              "format": "uuid"
-            }
-          },
-          {
-            "name": "sfdc_dw_dnt",
-            "in": "header",
-            "required": false,
-            "style": "simple",
-            "explode": false,
-            "schema": {
-              "type": "string",
-              "enum": [
-                "0",
-                "1"
-              ]
+              "format": "uuid",
+              "example": "550e8400-e29b-41d4-a716-446655440000"
             }
           },
           {
             "name": "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,
@@ -362,6 +453,11 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ConsentSubscriptionBulkRequest"
+              },
+              "examples": {
+                "ConsentSubscriptionBulkUpdateRequest": {
+                  "$ref": "#/components/examples/ConsentSubscriptionBulkUpdateRequest"
+                }
               }
             }
           },
@@ -374,6 +470,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ConsentSubscriptionBulkResponse"
+                },
+                "examples": {
+                  "ConsentSubscriptionBulkUpdateResponseSuccess": {
+                    "$ref": "#/components/examples/ConsentSubscriptionBulkUpdateResponseSuccess"
+                  }
                 }
               }
             }
@@ -384,6 +485,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ConsentSubscriptionBulkResponse"
+                },
+                "examples": {
+                  "ConsentSubscriptionBulkUpdateResponsePartial": {
+                    "$ref": "#/components/examples/ConsentSubscriptionBulkUpdateResponsePartial"
+                  }
                 }
               }
             }
@@ -394,6 +500,11 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "BulkValidationError": {
+                    "$ref": "#/components/examples/BulkValidationError"
+                  }
                 }
               }
             }
@@ -418,27 +529,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"
@@ -453,11 +575,15 @@
       },
       "Tag": {
         "type": "string",
+        "description": "Filter criteria for consent subscriptions",
+        "example": "homepage_banner",
         "maxLength": 256,
         "minLength": 1
       },
       "SubscriptionId": {
         "type": "string",
+        "description": "Identifier for the communication subscription",
+        "example": "weekly-newsletter",
         "maxLength": 255,
         "minLength": 1,
         "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
@@ -468,10 +594,15 @@
           "email",
           "sms",
           "whatsapp"
-        ]
+        ],
+        "example": "email"
       },
       "SubscriptionChannel": {
         "type": "array",
+        "example": [
+          "email",
+          "sms"
+        ],
         "items": {
           "$ref": "#/components/schemas/ChannelType"
         },
@@ -481,19 +612,29 @@
       },
       "ContactPointValue": {
         "type": "string",
+        "description": "The customer's contact point value, polymorphic based on the channel type as below:\n- `sms` - Subject's phone number in E.164 format, ex: `+1 424 535 3546`\n- `email` - Subject's email address in RFC 5321 & RFC 5322 format, ex: `jack.sparrow@salesforce.com`\n",
+        "example": "jack.sparrow@salesforce.com",
         "maxLength": 320,
         "minLength": 3
       },
       "ConsentStatus": {
         "type": "string",
+        "description": "The consent status of the subscription as supplied or recorded by this system",
         "enum": [
           "opt_in",
           "opt_out"
-        ]
+        ],
+        "example": "opt_in"
       },
       "SubscriptionStatusEntry": {
         "type": "object",
         "additionalProperties": false,
+        "description": "Individual subscription status entry for a specific channel",
+        "example": {
+          "channel": "email",
+          "contactPointValue": "john.doe@example.com",
+          "status": "opt_in"
+        },
         "properties": {
           "channel": {
             "$ref": "#/components/schemas/ChannelType"
@@ -513,6 +654,19 @@
       },
       "SubscriptionStatusArray": {
         "type": "array",
+        "description": "Array of subscription status entries for different channels",
+        "example": [
+          {
+            "channel": "email",
+            "contactPointValue": "john.doe@example.com",
+            "status": "opt_in"
+          },
+          {
+            "channel": "sms",
+            "contactPointValue": "+1 555 123 4567",
+            "status": "opt_out"
+          }
+        ],
         "items": {
           "$ref": "#/components/schemas/SubscriptionStatusEntry"
         },
@@ -521,11 +675,15 @@
       },
       "SubscriptionTitle": {
         "type": "string",
+        "description": "The localized title of the subscription for shopper displays",
+        "example": "Weekly Newsletter",
         "maxLength": 255,
         "minLength": 1
       },
       "SubscriptionSubtitle": {
         "type": "string",
+        "description": "The localized subtitle of the subscription for shopper displays, may contain HTML markup",
+        "example": "Stay informed about new features. <a href=\"https://example.com/features\">Learn more</a>",
         "maxLength": 2000,
         "minLength": 1
       },
@@ -543,7 +701,8 @@
               {
                 "$ref": "#/components/schemas/SubscriptionStatusArray"
               }
-            ]
+            ],
+            "description": "Subscription status information across different channels. This field is only included in the response\nwhen the 'expand' parameter contains \"consentStatus\". For privacy and performance\nreasons, status is not returned by default.\n"
           },
           "title": {
             "$ref": "#/components/schemas/SubscriptionTitle"
@@ -554,6 +713,10 @@
           "tags": {
             "type": "array",
             "default": [],
+            "example": [
+              "homepage_banner",
+              "user_profile"
+            ],
             "items": {
               "$ref": "#/components/schemas/Tag"
             },
@@ -563,22 +726,28 @@
           "consentType": {
             "type": "string",
             "default": "marketing",
+            "description": "Type of consent subscription",
             "enum": [
               "marketing",
               "legal"
-            ]
+            ],
+            "example": "marketing"
           },
           "consentRequired": {
             "type": "boolean",
-            "default": false
+            "default": false,
+            "description": "Whether this subscription is mandatory for the user",
+            "example": false
           },
           "defaultStatus": {
             "type": "string",
             "default": "opt_out",
+            "description": "Default consent status for this subscription",
             "enum": [
               "opt_in",
               "opt_out"
-            ]
+            ],
+            "example": "opt_out"
           }
         },
         "required": [
@@ -588,6 +757,7 @@
       },
       "ConsentSubscriptionResponse": {
         "type": "object",
+        "description": "Collection wrapper of consent subscriptions",
         "properties": {
           "data": {
             "type": "array",
@@ -608,17 +778,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
           }
         },
@@ -630,6 +808,7 @@
       },
       "ConsentSubscriptionRequest": {
         "type": "object",
+        "description": "Consent subscription update request",
         "properties": {
           "subscriptionId": {
             "$ref": "#/components/schemas/SubscriptionId"
@@ -653,6 +832,7 @@
       },
       "ConsentSubscriptionUpdateResponse": {
         "type": "object",
+        "description": "Single subscription update response",
         "properties": {
           "subscriptionId": {
             "$ref": "#/components/schemas/SubscriptionId"
@@ -676,9 +856,25 @@
       },
       "ConsentSubscriptionBulkRequest": {
         "type": "object",
+        "description": "Bulk request for updating multiple consent subscriptions",
         "properties": {
           "subscriptions": {
             "type": "array",
+            "description": "Array of subscription consent updates to process",
+            "example": [
+              {
+                "subscriptionId": "weekly-newsletter",
+                "channel": "email",
+                "contactPointValue": "john.doe@example.com",
+                "status": "opt_in"
+              },
+              {
+                "subscriptionId": "sms-alerts",
+                "channel": "sms",
+                "contactPointValue": "+1 555 123 4567",
+                "status": "opt_out"
+              }
+            ],
             "items": {
               "$ref": "#/components/schemas/ConsentSubscriptionRequest"
             },
@@ -692,18 +888,28 @@
       },
       "ConsentSubscriptionError": {
         "type": "object",
+        "description": "Error details for failed subscription updates",
         "properties": {
           "code": {
             "type": "string",
+            "description": "Error code indicating the type of failure",
+            "example": "INVALID_CONTACT_POINT",
             "maxLength": 100
           },
           "message": {
             "type": "string",
+            "description": "Human-readable error message",
+            "example": "Invalid email address format",
             "maxLength": 500
           },
           "details": {
             "type": "object",
-            "additionalProperties": false
+            "additionalProperties": false,
+            "description": "Additional error details",
+            "example": {
+              "field": "contactPointValue",
+              "provided": "invalid-email"
+            }
           }
         },
         "required": [
@@ -713,6 +919,7 @@
       },
       "ConsentSubscriptionResult": {
         "type": "object",
+        "description": "Individual subscription update result with input parameters",
         "properties": {
           "subscriptionId": {
             "$ref": "#/components/schemas/SubscriptionId"
@@ -727,14 +934,17 @@
             "$ref": "#/components/schemas/ConsentStatus"
           },
           "success": {
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Whether the subscription update was successful",
+            "example": true
           },
           "error": {
             "allOf": [
               {
                 "$ref": "#/components/schemas/ConsentSubscriptionError"
               }
-            ]
+            ],
+            "description": "Error details (present when success is false)"
           }
         },
         "required": [
@@ -747,9 +957,11 @@
       },
       "ConsentSubscriptionBulkResponse": {
         "type": "object",
+        "description": "Bulk response with results for each subscription update request",
         "properties": {
           "results": {
             "type": "array",
+            "description": "Results for each subscription update request",
             "items": {
               "$ref": "#/components/schemas/ConsentSubscriptionResult"
             }
@@ -764,36 +976,54 @@
       "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"
+          }
         }
       },
       "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"
+          }
         }
       },
       "tags": {
         "name": "tags",
         "in": "query",
+        "description": "Optional parameter of 0 or more query string values which act as a filtering criteria. Multiple values are treated with `OR` logic, and absence of a value indicates no filtering by tag is desired.",
         "required": false,
         "style": "form",
         "explode": false,
@@ -804,11 +1034,29 @@
           },
           "maxItems": 10,
           "minItems": 0
+        },
+        "examples": {
+          "one": {
+            "summary": "One tag filter",
+            "value": [
+              "homepage_banner"
+            ]
+          },
+          "multiple": {
+            "summary": "Multiple tag filters (ORs)",
+            "value": [
+              "homepage_banner",
+              "user_profile",
+              "checkout",
+              "registration"
+            ]
+          }
         }
       },
       "expand": {
         "name": "expand",
         "in": "query",
+        "description": "Optional parameter to expand response with additional fields. \nAccepts an array of field names to include in the response.\nCurrently supports:\n- \"consentStatus\": Include consent status information in the response\n\nFuture expansions may include additional fields.\n",
         "required": false,
         "style": "form",
         "explode": false,
@@ -819,41 +1067,43 @@
             "type": "string",
             "enum": [
               "consentStatus"
-            ]
+            ],
+            "example": "consentStatus"
           },
           "maxItems": 10,
           "minItems": 0,
           "uniqueItems": true
+        },
+        "examples": {
+          "empty": {
+            "summary": "No expansion (default behavior)",
+            "value": []
+          },
+          "consentStatus": {
+            "summary": "Include status information",
+            "value": [
+              "consentStatus"
+            ]
+          }
         }
       },
       "sfdcUsid": {
         "name": "sfdc_usid",
         "in": "header",
+        "description": "A unique shopper identifier (USID) for tracking client context.\nUsed with endpoints secured with ShopperClientContextToken.\nThis header is required for all endpoints secured with ShopperClientContextToken.",
         "required": false,
         "style": "simple",
         "explode": false,
         "schema": {
           "type": "string",
-          "format": "uuid"
-        }
-      },
-      "sfdcDwDnt": {
-        "name": "sfdc_dw_dnt",
-        "in": "header",
-        "required": false,
-        "style": "simple",
-        "explode": false,
-        "schema": {
-          "type": "string",
-          "enum": [
-            "0",
-            "1"
-          ]
+          "format": "uuid",
+          "example": "550e8400-e29b-41d4-a716-446655440000"
         }
       },
       "personalized": {
         "name": "personalized",
         "in": "query",
+        "description": "Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.",
         "required": false,
         "style": "form",
         "explode": true,
@@ -861,12 +1111,14 @@
           "type": "string",
           "enum": [
             "none"
-          ]
+          ],
+          "example": "none"
         }
       },
       "sfdcShopperContext": {
         "name": "sfdc_shopper_context",
         "in": "header",
+        "description": "Shopper context information (for example clientIP, sourceCode, and customQualifiers)\npassed in from a trusted backend application.",
         "required": false,
         "style": "simple",
         "explode": false,
@@ -875,9 +1127,273 @@
         }
       }
     },
+    "examples": {
+      "ConsentSubscriptionResponseAuthenticated": {
+        "summary": "AUTHENTICATED shopper's available consent subscriptions",
+        "value": {
+          "data": [
+            {
+              "subscriptionId": "weekly-newsletter",
+              "channels": [
+                "email",
+                "whatsapp"
+              ],
+              "title": "Weekly Newsletter",
+              "subtitle": "Get our weekly newsletter with the latest updates. <a href=\"https://example.com/newsletter\">Learn more</a>",
+              "consentType": "marketing",
+              "consentRequired": false,
+              "defaultStatus": "opt_out",
+              "tags": [
+                "homepage_banner",
+                "user_profile"
+              ]
+            },
+            {
+              "subscriptionId": "promotional-offers",
+              "channels": [
+                "sms"
+              ],
+              "title": "Promotional Offers",
+              "subtitle": "Receive special promotional offers. <a href=\"https://example.com/offers\">View terms</a>",
+              "consentType": "marketing",
+              "consentRequired": false,
+              "defaultStatus": "opt_out",
+              "tags": [
+                "checkout"
+              ]
+            }
+          ]
+        }
+      },
+      "ConsentSubscriptionResponseAuthenticatedExpanded": {
+        "summary": "AUTHENTICATED shopper's consent subscriptions with expand=[\"consentStatus\"]",
+        "value": {
+          "data": [
+            {
+              "subscriptionId": "weekly-newsletter",
+              "channels": [
+                "email",
+                "whatsapp"
+              ],
+              "consentStatus": [
+                {
+                  "channel": "email",
+                  "contactPointValue": "customer@example.com",
+                  "status": "opt_in"
+                },
+                {
+                  "channel": "whatsapp",
+                  "contactPointValue": "+1 555 123 4567",
+                  "status": "opt_out"
+                }
+              ],
+              "title": "Weekly Newsletter",
+              "subtitle": "Get our weekly newsletter with the latest updates. <a href=\"https://example.com/newsletter\">Learn more</a>",
+              "consentType": "marketing",
+              "consentRequired": false,
+              "defaultStatus": "opt_out",
+              "tags": [
+                "homepage_banner",
+                "user_profile"
+              ]
+            },
+            {
+              "subscriptionId": "promotional-offers",
+              "channels": [
+                "sms"
+              ],
+              "consentStatus": [
+                {
+                  "channel": "sms",
+                  "contactPointValue": "+1 555 987 6543",
+                  "status": "opt_out"
+                }
+              ],
+              "title": "Promotional Offers",
+              "subtitle": "Receive special promotional offers. <a href=\"https://example.com/offers\">View terms</a>",
+              "consentType": "marketing",
+              "consentRequired": false,
+              "defaultStatus": "opt_out",
+              "tags": [
+                "checkout",
+                "user_profile"
+              ]
+            },
+            {
+              "subscriptionId": "privacy-policy-updates",
+              "channels": [
+                "email"
+              ],
+              "consentStatus": [
+                {
+                  "channel": "email",
+                  "contactPointValue": "customer@example.com",
+                  "status": "opt_in"
+                }
+              ],
+              "title": "Privacy Policy Updates",
+              "subtitle": "Important updates to our privacy policy. <a href=\"https://example.com/privacy\">Read policy</a>",
+              "consentType": "legal",
+              "consentRequired": true,
+              "defaultStatus": "opt_in",
+              "tags": [
+                "registration"
+              ]
+            }
+          ]
+        }
+      },
+      "ConsentSubscriptionResponseGuest": {
+        "summary": "GUEST shopper's available consent subscriptions",
+        "value": {
+          "data": [
+            {
+              "subscriptionId": "weekly-newsletter",
+              "channels": [
+                "email",
+                "whatsapp"
+              ],
+              "title": "Weekly Newsletter",
+              "subtitle": "Get our weekly newsletter with the latest updates. <a href=\"https://example.com/newsletter\">Learn more</a>",
+              "consentType": "marketing",
+              "consentRequired": false,
+              "defaultStatus": "opt_out",
+              "tags": [
+                "homepage_banner",
+                "user_profile"
+              ]
+            },
+            {
+              "subscriptionId": "promotional-offers",
+              "channels": [
+                "sms"
+              ],
+              "title": "Promotional Offers",
+              "subtitle": "Receive special promotional offers. <a href=\"https://example.com/offers\">View terms</a>",
+              "consentType": "marketing",
+              "consentRequired": false,
+              "defaultStatus": "opt_out",
+              "tags": [
+                "checkout"
+              ]
+            }
+          ]
+        }
+      },
+      "ConsentSubscriptionError": {
+        "value": {
+          "title": "Error Retrieving Consent Subscription",
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
+          "detail": "Error retrieving consent subscription."
+        }
+      },
+      "ConsentSubscriptionUpdateRequest": {
+        "summary": "Single subscription update request",
+        "value": {
+          "subscriptionId": "weekly-newsletter",
+          "contactPointValue": "john.doe@example.com",
+          "channel": "email",
+          "status": "opt_in"
+        }
+      },
+      "ConsentSubscriptionUpdateResponseSuccess": {
+        "summary": "Single subscription update successful (200 response)",
+        "value": {
+          "subscriptionId": "weekly-newsletter",
+          "contactPointValue": "john.doe@example.com",
+          "channel": "email",
+          "status": "opt_in"
+        }
+      },
+      "ConsentSubscriptionUpdateError": {
+        "value": {
+          "title": "Error Updating Consent Subscription",
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
+          "detail": "Consent subscription could not be updated."
+        }
+      },
+      "ConsentSubscriptionBulkUpdateRequest": {
+        "summary": "Bulk subscription update request",
+        "value": {
+          "subscriptions": [
+            {
+              "subscriptionId": "weekly-newsletter",
+              "contactPointValue": "john.doe@example.com",
+              "channel": "email",
+              "status": "opt_in"
+            },
+            {
+              "subscriptionId": "sms-alerts",
+              "contactPointValue": "+1 555 123 4567",
+              "channel": "sms",
+              "status": "opt_out"
+            }
+          ]
+        }
+      },
+      "ConsentSubscriptionBulkUpdateResponseSuccess": {
+        "summary": "All subscription updates successful (200 response)",
+        "value": {
+          "results": [
+            {
+              "subscriptionId": "weekly-newsletter",
+              "contactPointValue": "john.doe@example.com",
+              "channel": "email",
+              "status": "opt_in",
+              "success": true
+            },
+            {
+              "subscriptionId": "sms-alerts",
+              "contactPointValue": "+1 555 123 4567",
+              "channel": "sms",
+              "status": "opt_out",
+              "success": true
+            }
+          ]
+        }
+      },
+      "ConsentSubscriptionBulkUpdateResponsePartial": {
+        "summary": "Partial success - some updates failed (207 response)",
+        "value": {
+          "results": [
+            {
+              "subscriptionId": "weekly-newsletter",
+              "contactPointValue": "john.doe@example.com",
+              "channel": "email",
+              "status": "opt_in",
+              "success": true
+            },
+            {
+              "subscriptionId": "sms-alerts",
+              "contactPointValue": "invalid-phone",
+              "channel": "sms",
+              "status": "opt_out",
+              "success": false,
+              "error": {
+                "code": "INVALID_CONTACT_POINT",
+                "message": "Invalid phone number format",
+                "details": {
+                  "field": "contactPointValue",
+                  "provided": "invalid-phone"
+                }
+              }
+            }
+          ]
+        }
+      },
+      "BulkValidationError": {
+        "value": {
+          "title": "Bulk Request Validation Error",
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
+          "detail": "One or more validation errors occurred in the bulk request.",
+          "instance": "/organizations/f_ecom_zzrf_001/subscriptions"
+        }
+      }
+    },
     "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 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",
@@ -898,6 +1414,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",