@salesforce/b2c-tooling-sdk 2.3.0 → 2.5.0

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

@@ -2,7 +2,8 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Shopper Context",
-    "version": "1.1.3",
+    "description": "[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-context/shopper-context-oas-v1-public.yaml)\n\n# API Overview\n\nWith the Shopper Context API, you can set any context information as a key/value pair and use it to retrieve personalized promotions, payment methods, and shipping methods. The context information that is set is evaluated against the customer group definitions to determine a customer group (shopper segment), and is then used to activate the experiences that are associated with a particular segment, such as promotions.\n\nYou can also get personalized API responses triggered by shopper context from the [Open Commerce API](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/get-started-with-ocapi.html) (OCAPI). Support for both the B2C Commerce API and OCAPI allows shopper context to be used in hybrid deployments.\n\n**Warning** \nAccess tokens with a scope that includes the Shopper Context API are powerful. They can activate specific promotions and can be used to see how a storefront would be displayed in the future. Don't share them with untrusted clients like web browsers or client apps.\n\nMake Shopper Context calls with a private client and only set shopper context through a secure backend channel. To avoid misuse, do not make direct calls through a browser or similar client in which data can be viewed. \n\nAs part of this, when creating a SLAS public client for a tenant, if you attempt to add the Shopper Context API scope, a warning message is displayed to ensure you are aware of the pitfalls of doing so.\n\n**Note**:\n\nShopper context is valid for 1 day for guest shoppers and 7 days for registered shoppers. To extend the context set, create a new context. As a best practice, refresh your contexts periodically to ensure that the right personalized experience is rendered for your shoppers.\n\n## Authentication & Authorization\n\nThe Shopper Context API requires a shopper access token from the Shopper Login and API Access Service (SLAS).\n\nYou must include `sfcc.shopper-context.rw` in the client ID used to generate the SLAS token. For a full list of 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\nFor more information, see [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html) in the Get Started guides.            \n\n**Warning**: As with all APIs, never store access tokens in the browser because this creates a security vulnerability.\n\n## Customization\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## 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. Shopper context is per-shopper state that changes with each context update.\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### Set Shopper Context\n\nSet context attributes for a shopper to personalize subsequent API responses.\n\n```sh\ncurl \"https://{shortCode}.api.commercecloud.salesforce.com/shopper/shopper-context/v1/organizations/{organizationId}/shopper-context/{usid}?siteId=RefArch\" \\\n  -X PUT \\\n  -H \"Authorization: Bearer {access_token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"customQualifiers\": { \"deviceType\": \"mobile\" }, \"assignmentQualifiers\": { \"storeId\": \"boston\" } }'\n```\n\n\nFor detailed usage information, see the [Shopper Context guides](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html).",
+    "version": "1.1.4",
     "x-api-type": "Shopper",
     "x-api-family": "Shopper"
   },
@@ -11,6 +12,7 @@
       "url": "https://{shortCode}.api.commercecloud.salesforce.com/shopper/shopper-context/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,11 +21,13 @@
   "paths": {
     "/organizations/{organizationId}/shopper-context/{usid}": {
       "get": {
+        "summary": "Get the shopper's context based on the shopperJWT.",
         "operationId": "getShopperContext",
         "parameters": [
           {
             "name": "usid",
             "in": "path",
+            "description": "The Shopper's unique identifier. It is a required parameter and is part of the response from the Guest or Registered User Shopper Login (SLAS) API call.",
             "required": true,
             "style": "simple",
             "explode": false,
@@ -34,21 +38,38 @@
           {
             "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 site context.",
             "required": true,
             "style": "form",
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/SiteId"
+            },
+            "example": "RefArch"
+          },
+          {
+            "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",
+              "example": "550e8400-e29b-41d4-a716-446655440000"
             }
           }
         ],
@@ -57,11 +78,13 @@
             "description": "Shopper Context retrieved successfully.",
             "headers": {
               "X-Geolocation": {
+                "description": "The response header returns the geolocation based on the `clientIp` or `geoLocation` attribute set in the shopper context. If both are set, `geoLocation` takes precedence.",
                 "required": false,
                 "style": "simple",
                 "explode": false,
                 "schema": {
-                  "type": "string"
+                  "type": "string",
+                  "example": "CountryCode: US; Country: United States; MetroCode: 0; Latitude: 37.751; Longitude: -97.822"
                 }
               }
             },
@@ -69,6 +92,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ShopperContext"
+                },
+                "examples": {
+                  "ShopperContextExample": {
+                    "$ref": "#/components/examples/ShopperContextExample"
+                  }
                 }
               }
             }
@@ -76,9 +104,14 @@
           "400": {
             "description": "The usid in the incoming request does not match the usid in the token.",
             "content": {
-              "application/json": {
+              "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "getShopperContext400": {
+                    "$ref": "#/components/examples/BadRequestUSIDNotMatching"
+                  }
                 }
               }
             }
@@ -86,9 +119,14 @@
           "401": {
             "description": "Your shopper JWT is invalid and cannot be used to identify the API client.",
             "content": {
-              "application/json": {
+              "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "getShopperContext401": {
+                    "$ref": "#/components/examples/Unauthorized"
+                  }
                 }
               }
             }
@@ -96,9 +134,14 @@
           "403": {
             "description": "Your shopper JWT is valid, but you do not have permission to access the resource.",
             "content": {
-              "application/json": {
+              "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "getShopperContext403": {
+                    "$ref": "#/components/examples/Forbidden"
+                  }
                 }
               }
             }
@@ -106,9 +149,14 @@
           "404": {
             "description": "Shopper Context for ORGANIZATION_ID - f_ecom_bhbv_prd and USID - 7e1f65fb-185c-4788-8cec-05fef8dac77d not found in repository.",
             "content": {
-              "application/json": {
+              "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "getShopperContext404": {
+                    "$ref": "#/components/examples/NotFound"
+                  }
                 }
               }
             }
@@ -120,15 +168,23 @@
               "sfcc.shopper-context",
               "sfcc.shopper-context.rw"
             ]
+          },
+          {
+            "ShopperClientContextToken": [
+              "sfcc.shopper-context",
+              "sfcc.shopper-context.rw"
+            ]
           }
         ]
       },
       "put": {
+        "summary": "Create the shopper's context based on the shopperJWT. If a shopper context already exists, the entire existing context is replaced.",
         "operationId": "createShopperContext",
         "parameters": [
           {
             "name": "usid",
             "in": "path",
+            "description": "The Shopper's unique identifier. It is a required parameter and is part of the response from the Guest or Registered User Shopper Login (SLAS) API call.",
             "required": true,
             "style": "simple",
             "explode": false,
@@ -139,32 +195,50 @@
           {
             "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 site context.",
             "required": true,
             "style": "form",
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/SiteId"
-            }
+            },
+            "example": "RefArch"
           },
           {
             "name": "evaluateContextWithClientIp",
             "in": "query",
+            "description": "Determines whether to evaluate the context using the provided `clientIp`.  This property is available with B2C Commerce version 24.7.\n- If `evaluateContextWithClientIp` is set to `true`:\n  - The `clientIP` is saved and used in subsequent requests.\n\n- If `evaluateContextWithClientIp` is set to `false`:\n  - The `clientIP` is not saved and will not be used in subsequent requests.\n",
             "required": false,
             "style": "form",
             "explode": true,
             "schema": {
               "type": "boolean"
             }
+          },
+          {
+            "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",
+              "example": "550e8400-e29b-41d4-a716-446655440000"
+            }
           }
         ],
         "requestBody": {
@@ -172,6 +246,11 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ShopperContext"
+              },
+              "examples": {
+                "ShopperContextExample": {
+                  "$ref": "#/components/examples/ShopperContextExample"
+                }
               }
             }
           },
@@ -182,6 +261,7 @@
             "description": "The shopper's context was created successfully.",
             "headers": {
               "X-Geolocation": {
+                "description": "The response header returns the geolocation based on the `clientIp` or `geoLocation` attribute set in the shopper context. If both are set, `geoLocation` takes precedence.",
                 "required": false,
                 "style": "simple",
                 "explode": false,
@@ -195,6 +275,7 @@
             "description": "The shopper's context was created successfully.",
             "headers": {
               "X-Geolocation": {
+                "description": "The response header returns the geolocation based on the `clientIp` or `geoLocation` attribute set in the shopper context. If both are set, `geoLocation` takes precedence.",
                 "required": false,
                 "style": "simple",
                 "explode": false,
@@ -207,9 +288,14 @@
           "400": {
             "description": "The usid in the incoming request does not match the usid in the token.",
             "content": {
-              "application/json": {
+              "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "getShopperContext400": {
+                    "$ref": "#/components/examples/BadRequestUSIDNotMatching"
+                  }
                 }
               }
             }
@@ -217,9 +303,14 @@
           "401": {
             "description": "Your shopper JWT is invalid and cannot be used to identify the API client.",
             "content": {
-              "application/json": {
+              "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "getShopperContext401": {
+                    "$ref": "#/components/examples/Unauthorized"
+                  }
                 }
               }
             }
@@ -227,9 +318,14 @@
           "403": {
             "description": "Your shopper JWT is valid, but you do not have permission to access the resource.",
             "content": {
-              "application/json": {
+              "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "Forbidden": {
+                    "$ref": "#/components/examples/Forbidden"
+                  }
                 }
               }
             }
@@ -240,15 +336,22 @@
             "ShopperToken": [
               "sfcc.shopper-context.rw"
             ]
+          },
+          {
+            "ShopperClientContextToken": [
+              "sfcc.shopper-context.rw"
+            ]
           }
         ]
       },
       "delete": {
+        "description": "Delete the shopper's context based on the shopperJWT.",
         "operationId": "deleteShopperContext",
         "parameters": [
           {
             "name": "usid",
             "in": "path",
+            "description": "The Shopper's unique identifier. It is a required parameter and is part of the response from the Guest or Registered User Shopper Login (SLAS) API call.",
             "required": true,
             "style": "simple",
             "explode": false,
@@ -259,21 +362,38 @@
           {
             "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 site context.",
             "required": true,
             "style": "form",
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/SiteId"
+            },
+            "example": "RefArch"
+          },
+          {
+            "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",
+              "example": "550e8400-e29b-41d4-a716-446655440000"
             }
           }
         ],
@@ -284,9 +404,14 @@
           "400": {
             "description": "The usid in the incoming request does not match the usid in the token.",
             "content": {
-              "application/json": {
+              "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "getShopperContext400": {
+                    "$ref": "#/components/examples/BadRequestUSIDNotMatching"
+                  }
                 }
               }
             }
@@ -294,9 +419,14 @@
           "401": {
             "description": "Your shopper JWT is invalid and cannot be used to identify the API client.",
             "content": {
-              "application/json": {
+              "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "getShopperContext401": {
+                    "$ref": "#/components/examples/Unauthorized"
+                  }
                 }
               }
             }
@@ -304,9 +434,14 @@
           "403": {
             "description": "Your shopper JWT is valid, but you do not have permission to access the resource.",
             "content": {
-              "application/json": {
+              "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "Forbidden": {
+                    "$ref": "#/components/examples/Forbidden"
+                  }
                 }
               }
             }
@@ -314,9 +449,14 @@
           "404": {
             "description": "Shopper Context for ORGANIZATION_ID - f_ecom_bhbv_prd and USID - 7e1f65fb-185c-4788-8cec-05fef8dac77d not found in repository.",
             "content": {
-              "application/json": {
+              "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "getShopperContext404": {
+                    "$ref": "#/components/examples/NotFound"
+                  }
                 }
               }
             }
@@ -327,15 +467,23 @@
             "ShopperToken": [
               "sfcc.shopper-context.rw"
             ]
+          },
+          {
+            "ShopperClientContextToken": [
+              "sfcc.shopper-context.rw"
+            ]
           }
         ]
       },
       "patch": {
+        "summary": "Update an existing shopper's context based on the Shopper JWT.",
+        "description": "If the shopper context exists, it's updated with the patch body.\n- If a new attribute that does not exist in the existing shopper context is present, it is added to the context.\n-If an attribute is already present in the existing shopper context, its value is replaced by the corresponding value from the new shopper context in the request body as follows:\n  - `custom qualifiers` or `assignment qualifiers`:\n\n  If the individual qualifier key exists, it is overwritten with the new value.\n\n  If the value of the key is set to null, it is deleted from the existing shopper context.\n\n  If an empty `custom qualifiers` or `assignment qualifiers` object `{}` is passed, the entire qualifier object is deleted.\n  - `effectiveDateTime` or `sourceCode` or `clientIp`:\n\n  If the new value is set to an empty string (\"\"), it is deleted from the existing shopper context.\n\n  If the new value is set to null, it is ignored.\n\n  If the new value is not empty or null, it overwrites the existing value.\n\n  - `customerGroupIds`:\n\n  If a list of `customerGroupIds` exists, it is replaced by the new list of customer group IDs from the request.\n\n  If `customerGroupIds` is set to an empty array [], the existing list in the shopper context is deleted.\n\n  - `geoLocation`:  \n\n  If it exists, the entire `geoLocation` object is replaced with the new value.\n\n  If the new value is set to null, it is ignored.\n\n  If an empty `geoLocation` object `{}` is passed, it is deleted.",
         "operationId": "updateShopperContext",
         "parameters": [
           {
             "name": "usid",
             "in": "path",
+            "description": "The Shopper's unique identifier. It is a required parameter and is part of the response from the Guest or Registered User Shopper Login (SLAS) API call.",
             "required": true,
             "style": "simple",
             "explode": false,
@@ -346,32 +494,50 @@
           {
             "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 site context.",
             "required": true,
             "style": "form",
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/SiteId"
-            }
+            },
+            "example": "RefArch"
           },
           {
             "name": "evaluateContextWithClientIp",
             "in": "query",
+            "description": "Determines whether to evaluate the context using the provided `clientIp`.  This property is available with B2C Commerce version 24.7.\n- If `evaluateContextWithClientIp` is set to `true`:\n  - The `clientIP` is saved and used in subsequent requests.\n\n- If `evaluateContextWithClientIp` is set to `false`:\n  - The `clientIP` is not saved and will not be used in subsequent requests.\n",
             "required": false,
             "style": "form",
             "explode": true,
             "schema": {
               "type": "boolean"
             }
+          },
+          {
+            "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",
+              "example": "550e8400-e29b-41d4-a716-446655440000"
+            }
           }
         ],
         "requestBody": {
@@ -379,6 +545,11 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ShopperContext"
+              },
+              "examples": {
+                "ShopperContextUpdateRequestBody": {
+                  "$ref": "#/components/examples/ShopperContextUpdateRequestBody"
+                }
               }
             }
           },
@@ -401,6 +572,11 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ShopperContext"
+                },
+                "examples": {
+                  "ShopperContextUpdateResponseExample": {
+                    "$ref": "#/components/examples/ShopperContextUpdateResponseExample"
+                  }
                 }
               }
             }
@@ -408,9 +584,14 @@
           "400": {
             "description": "The usid in the incoming request does not match the usid in the token.",
             "content": {
-              "application/json": {
+              "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "updateShopperContext400": {
+                    "$ref": "#/components/examples/BadRequestUSIDNotMatching"
+                  }
                 }
               }
             }
@@ -418,9 +599,14 @@
           "401": {
             "description": "Your shopper JWT is invalid and cannot be used to identify the API client.",
             "content": {
-              "application/json": {
+              "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "updateShopperContext401": {
+                    "$ref": "#/components/examples/Unauthorized"
+                  }
                 }
               }
             }
@@ -428,9 +614,14 @@
           "403": {
             "description": "Your shopper JWT is valid, but you do not have permission to access the resource.",
             "content": {
-              "application/json": {
+              "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "updateShopperContext403": {
+                    "$ref": "#/components/examples/Forbidden"
+                  }
                 }
               }
             }
@@ -441,6 +632,11 @@
             "ShopperToken": [
               "sfcc.shopper-context.rw"
             ]
+          },
+          {
+            "ShopperClientContextToken": [
+              "sfcc.shopper-context.rw"
+            ]
           }
         ]
       }
@@ -450,29 +646,60 @@
     "schemas": {
       "OrganizationId": {
         "type": "string",
-        "maxLength": 32,
-        "minLength": 1
+        "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
       },
       "ShopperContext": {
         "type": "object",
         "additionalProperties": false,
+        "description": "A shoppers' context represented as key-value string pairs.",
+        "example": {
+          "effectiveDateTime": "2020-12-20T00:00:00Z",
+          "sourceCode": "wii1-98",
+          "customQualifiers": {
+            "deviceType": "mobile",
+            "ipAddress": "189.0.0.0",
+            "operatingSystem": "Android"
+          },
+          "assignmentQualifiers": {
+            "store": "boston"
+          },
+          "customerGroupIds": [
+            "BigSpenders",
+            "MobileUsers"
+          ],
+          "clientIp": "12.12.12.1",
+          "couponCodes": [
+            "Save20",
+            "FREESHIP"
+          ]
+        },
         "properties": {
           "effectiveDateTime": {
             "type": "string",
-            "format": "date-time"
+            "format": "date-time",
+            "description": "Qualifier to set the effective date time for the context to apply. For example, \"Shop the Future\" use cases. If not provided, the current dateTime will be assumed.",
+            "example": "2020-12-20T00:00:00Z"
           },
           "sourceCode": {
-            "type": "string"
+            "type": "string",
+            "description": "Qualifier to set the source code for the context to apply. Set the source code to evaluate source code group that triggers the promotion (campaign assignment) and Price books (assigned to Source code group).",
+            "example": "wii1-98"
           },
           "customerGroupIds": {
             "type": "array",
+            "description": "Qualifier to set the Customer Group Ids for the context to apply. Set the Customer Group Ids to evaluate customer groups that trigger the promotions (campaign assignment) assigned to the customer groups.",
             "items": {
               "type": "string",
+              "example": "BigSpenders",
               "maxLength": 256
             }
           },
@@ -480,55 +707,88 @@
             "type": "object",
             "additionalProperties": {
               "type": "string"
+            },
+            "description": "Map of custom qualifiers for the shopper context. Set this object to trigger pricing and promotion experiences using a dynamic session-based customer group. Object size is limited to 20 key-value pairs (properties).",
+            "example": {
+              "deviceType": "mobile",
+              "ipAddress": "189.0.0.0",
+              "operatingSystem": "Android"
             }
           },
           "assignmentQualifiers": {
             "type": "object",
             "additionalProperties": {
-              "type": "string"
+              "type": "string",
+              "example": "{\"store\":\"boston\"}"
+            },
+            "description": "Map of assignment qualifiers for the shopper context. Set this object when using the assignment framework to activate experiences based on assignment qualifiers. Currently, only pricing and promotion experiences are supported. Object size is limited to 20 key-value pairs (properties).",
+            "example": {
+              "store": "boston"
             }
           },
           "clientIp": {
-            "type": "string"
+            "type": "string",
+            "description": "The IP Address of the client. If the client IP is not a valid IPv4 address, a Bad Request (400) error is thrown. This property is available with B2C Commerce version 24.7.\n\nWhen `clientIp` is set, the geolocation based on the `clientIp` is returned in the `X-Geolocation` header in the response. Note: Use/retrieve this header in a case insensitive manner.\n\nHowever, if the `geoLocation` attribute is also set in the context, it takes precedence over the `clientIp`, and the `X-Geolocation` header returns the geolocation based on the `geoLocation` attribute.\n\nThe query parameter `evaluateContextWithClientIp` determines whether to evaluate the context using the provided `clientIp`.\n  - If `evaluateContextWithClientIp` is set to `true`:\n    - The `clientIp` is saved and used in subsequent requests. \n    \n    Note: If `geoLocation` is also saved in the context, it takes precedence over the `clientIp`.\n  - If `evaluateContextWithClientIp` is set to `false`:\n    - The `clientIp` is not saved and is not used in subsequent requests.",
+            "example": "12.12.12.1"
           },
           "geoLocation": {
             "type": "object",
+            "description": "The geographic location of the client. When you set a geolocation, it is saved as context for subsequent requests. This overrides any geolocation context previously saved using `clientIp`. This property is available with B2C Commerce version 24.7.",
             "properties": {
               "city": {
-                "type": "string"
+                "type": "string",
+                "description": "The city name associated with this location.",
+                "example": "Boston"
               },
               "country": {
-                "type": "string"
+                "type": "string",
+                "description": "The country name associated with this location.",
+                "example": "United States of America"
               },
               "countryCode": {
-                "type": "string"
+                "type": "string",
+                "description": "The ISO country code associated with this location.",
+                "example": "US"
               },
               "latitude": {
                 "type": "number",
-                "format": "double"
+                "format": "double",
+                "description": "The latitude coordinate, which is a number between -90.0 and +90.0, associated with this location.",
+                "example": 10.11
               },
               "longitude": {
                 "type": "number",
-                "format": "double"
+                "format": "double",
+                "description": "The longitude coordinate, which is a number between -180.0 and +180.0, associated with this location.",
+                "example": 198.34
               },
               "metroCode": {
-                "type": "string"
+                "type": "string",
+                "description": "The metro code associated with this location."
               },
               "postalCode": {
-                "type": "string"
+                "type": "string",
+                "description": "The postal code associated with this location.",
+                "example": "01730"
               },
               "region": {
-                "type": "string"
+                "type": "string",
+                "description": "The region (subdivision) name for this location. Corresponds with \"state\" in the USA.",
+                "example": "NA"
               },
               "regionCode": {
-                "type": "string"
+                "type": "string",
+                "description": "The region (province or state) code for this location.",
+                "example": "12345"
               }
             }
           },
           "couponCodes": {
             "type": "array",
+            "description": "Array of coupon codes to be saved in the shopper context. Set the coupon codes to evaluate promotions that can be triggered by these codes.",
             "items": {
               "type": "string",
+              "example": "SAVE20",
               "maxLength": 256
             }
           }
@@ -540,17 +800,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
           }
         },
@@ -565,6 +833,7 @@
       "usid": {
         "name": "usid",
         "in": "path",
+        "description": "The Shopper's unique identifier. It is a required parameter and is part of the response from the Guest or Registered User Shopper Login (SLAS) API call.",
         "required": true,
         "style": "simple",
         "explode": false,
@@ -575,37 +844,169 @@
       "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 site context.",
         "required": true,
         "style": "form",
         "explode": true,
         "schema": {
           "$ref": "#/components/schemas/SiteId"
-        }
+        },
+        "example": "RefArch"
       },
       "evaluateContextWithClientIp": {
         "name": "evaluateContextWithClientIp",
         "in": "query",
+        "description": "Determines whether to evaluate the context using the provided `clientIp`.  This property is available with B2C Commerce version 24.7.\n- If `evaluateContextWithClientIp` is set to `true`:\n  - The `clientIP` is saved and used in subsequent requests.\n\n- If `evaluateContextWithClientIp` is set to `false`:\n  - The `clientIP` is not saved and will not be used in subsequent requests.\n",
         "required": false,
         "style": "form",
         "explode": true,
         "schema": {
           "type": "boolean"
         }
+      },
+      "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",
+          "example": "550e8400-e29b-41d4-a716-446655440000"
+        }
+      }
+    },
+    "examples": {
+      "ShopperContextExample": {
+        "value": {
+          "effectiveDateTime": "2020-12-20T00:00:00Z",
+          "sourceCode": "wii1-98",
+          "customQualifiers": {
+            "deviceType": "mobile",
+            "ipAddress": "189.0.0.0",
+            "operatingSystem": "Android"
+          },
+          "assignmentQualifiers": {
+            "store": "boston"
+          },
+          "customerGroupIds": [
+            "BigSpenders",
+            "MobileUsers"
+          ],
+          "clientIp": "12.12.12.1",
+          "couponCodes": [
+            "Save20",
+            "FREESHIP"
+          ]
+        }
+      },
+      "BadRequestUSIDNotMatching": {
+        "value": {
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/usid-not-matching-with-token",
+          "detail": "Usid in incoming request does not match Usid in token.",
+          "title": "Usid not matching with token"
+        }
+      },
+      "Unauthorized": {
+        "value": {
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
+          "title": "Unauthorized",
+          "detail": "Your shopper JWT is invalid and could not be used to identify the API client."
+        }
+      },
+      "Forbidden": {
+        "value": {
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
+          "title": "Forbidden",
+          "detail": "Your shopper JWT is valid, but you have no permissions to access the resource."
+        }
+      },
+      "NotFound": {
+        "value": {
+          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/shopper-context-no-found",
+          "detail": "Shopper Context for ORGANIZATION_ID: f_ecom_bhbv_prd and USID: 7e1f65fb-185c-4788-8cec-05fef8dac77d not found in Repository.",
+          "title": "Shopper Context Not Found"
+        }
+      },
+      "ShopperContextUpdateRequestBody": {
+        "value": {
+          "customQualifiers": {
+            "deviceType": "iPad",
+            "storeId": "SLC1"
+          },
+          "assignmentQualifiers": {
+            "store": "london"
+          },
+          "clientIp": "12.12.12.1",
+          "geoLocation": {
+            "countryCode": "US",
+            "country": "United States of America",
+            "city": "Boston",
+            "postalCode": "01730",
+            "metroCode": "M234",
+            "region": "NA",
+            "regionCode": "12345",
+            "latitude": 10.11,
+            "longitude": 198.34
+          },
+          "couponCodes": [
+            "Save20",
+            "FREESHIP"
+          ]
+        }
+      },
+      "ShopperContextUpdateResponseExample": {
+        "value": {
+          "sourceCode": "wii1-98",
+          "customQualifiers": {
+            "deviceType": "iPad",
+            "ipAddress": "189.0.0.0",
+            "storeId": "SLC1"
+          },
+          "assignmentQualifiers": {
+            "store": "london"
+          },
+          "customerGroupIds": [
+            "BigSpenders",
+            "MobileUsers"
+          ],
+          "clientIp": "12.12.12.1",
+          "geoLocation": {
+            "countryCode": "US",
+            "country": "United States of America",
+            "city": "Boston",
+            "postalCode": "01730",
+            "metroCode": "M234",
+            "region": "NA",
+            "regionCode": "12345",
+            "latitude": 10.11,
+            "longitude": 198.34
+          },
+          "couponCodes": [
+            "Save20",
+            "FREESHIP"
+          ]
+        }
       }
     },
     "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",
@@ -615,8 +1016,21 @@
             }
           },
           "authorizationCode": {
-            "authorizationUrl": "https://{short-code}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize",
-            "tokenUrl": "https://{short-code}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token",
+            "authorizationUrl": "https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize",
+            "tokenUrl": "https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token",
+            "scopes": {
+              "sfcc.shopper-context": "Shopper Context READONLY",
+              "sfcc.shopper-context.rw": "Shopper Context"
+            }
+          }
+        }
+      },
+      "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",
             "scopes": {
               "sfcc.shopper-context": "Shopper Context READONLY",
               "sfcc.shopper-context.rw": "Shopper Context"