--- schema_version: "1" id: d1acf528e909a8231f4d7b6040eee0031bb26195e2a8e0e691902bb7a75c9959 title: Shopper Context collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-context.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context source_site: developer.salesforce.com content_type: documentation content_hash: 7f097eb0a5b52e566ea4fd59f51e96375b2584122a55448502e9a1f8d36f2bc0 products: - B2C Commerce API - Salesforce APIs --- Shopper Context # Shopper Context [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-context/shopper-context-oas-v1-public.yaml) ## API Overview With 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. You 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. **Warning** Access 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. Make 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. As 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. **Note**: Shopper 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. ### Authentication & Authorization The Shopper Context API requires a shopper access token from the Shopper Login and API Access Service (SLAS). You 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) For 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. For 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. **Warning**: As with all APIs, never store access tokens in the browser because this creates a security vulnerability. ### Customization #### Hooks For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html) ### Response Details #### Personalization Responses from this API are not personalized via the Shopper Context API. #### Caching Responses from this API are not cached. Shopper context is per-shopper state that changes with each context update. #### Timeouts Shopper 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) #### Error Handling Error 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) ### Use Cases #### Set Shopper Context Set context attributes for a shopper to personalize subsequent API responses. ```sh curl "https://{shortCode}.api.commercecloud.salesforce.com/shopper/shopper-context/v1/organizations/{organizationId}/shopper-context/{usid}?siteId=RefArch" \ -X PUT \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -d '{ "customQualifiers": { "deviceType": "mobile" }, "assignmentQualifiers": { "storeId": "boston" } }' ``` For 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 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/shopper/shopper-context/v1` * `shortCode (default shortCode) 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)` ## Security * `ShopperToken` (oauth2) 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. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A 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. The `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. * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token) * Scope sfcc.shopper-context: Shopper Context READONLY * Scope sfcc.shopper-context.rw: Shopper Context * OAuth flow authorizationCode (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) * Scope sfcc.shopper-context: Shopper Context READONLY * Scope sfcc.shopper-context.rw: Shopper Context * `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only. * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context) * Scope sfcc.shopper-context: Shopper Context READONLY * Scope sfcc.shopper-context.rw: Shopper Context ## Operations ### GET Get the shopper's context based on the shopperJWT. `GET /organizations/{organizationId}/shopper-context/{usid}` Operation ID: `getShopperContext`. Security: ShopperToken (sfcc.shopper-context, sfcc.shopper-context.rw); ShopperClientContextToken (sfcc.shopper-context, sfcc.shopper-context.rw). #### Parameters * `usid` (path, string, required) 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. * `organizationId` (path, OrganizationId, required) 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 ``` * `siteId` (query, SiteId, required) The site context. _Example_ ``` RefArch ``` * `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken. Example: `550e8400-e29b-41d4-a716-446655440000`. #### Responses * **200** Shopper Context retrieved successfully. Headers: * `X-Geolocation` (string) 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. Example: `CountryCode: US; Country: United States; MetroCode: 0; Latitude: 37.751; Longitude: -97.822`. Media type: `application/json`. Schema: `ShopperContext`. _Example: ShopperContextExample_ ``` { "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" ] } ``` * **400** The usid in the incoming request does not match the usid in the token. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: getShopperContext400_ ``` { "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" } ``` * **401** Your shopper JWT is invalid and cannot be used to identify the API client. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: getShopperContext401_ ``` { "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." } ``` * **403** Your shopper JWT is valid, but you do not have permission to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: getShopperContext403_ ``` { "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." } ``` * **404** Shopper Context for ORGANIZATION\_ID - f\_ecom\_bhbv\_prd and USID - 7e1f65fb-185c-4788-8cec-05fef8dac77d not found in repository. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: getShopperContext404_ ``` { "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" } ``` ### PUT Create the shopper's context based on the shopperJWT. If a shopper context already exists, the entire existing context is replaced. `PUT /organizations/{organizationId}/shopper-context/{usid}` Operation ID: `createShopperContext`. Security: ShopperToken (sfcc.shopper-context.rw); ShopperClientContextToken (sfcc.shopper-context.rw). #### Parameters * `usid` (path, string, required) 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. * `organizationId` (path, OrganizationId, required) 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 ``` * `siteId` (query, SiteId, required) The site context. _Example_ ``` RefArch ``` * `evaluateContextWithClientIp` (query, boolean) Determines whether to evaluate the context using the provided `clientIp`. This property is available with B2C Commerce version 24.7. * If `evaluateContextWithClientIp` is set to `true`: * The `clientIP` is saved and used in subsequent requests. * If `evaluateContextWithClientIp` is set to `false`: * The `clientIP` is not saved and will not be used in subsequent requests. * `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken. Example: `550e8400-e29b-41d4-a716-446655440000`. #### Request body (required) Media type: `application/json`. Schema: `ShopperContext`. _Example ShopperContextExample: same as GET /organizations/{organizationId}/shopper-context/{usid} 200 response._ #### Responses * **200** The shopper's context was created successfully. Headers: * `X-Geolocation` (string) 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. * **201** The shopper's context was created successfully. Headers: * `X-Geolocation` (string) 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. * **400** The usid in the incoming request does not match the usid in the token. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getShopperContext400: same as GET /organizations/{organizationId}/shopper-context/{usid} 400 response._ * **401** Your shopper JWT is invalid and cannot be used to identify the API client. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getShopperContext401: same as GET /organizations/{organizationId}/shopper-context/{usid} 401 response._ * **403** Your shopper JWT is valid, but you do not have permission to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example Forbidden: same as GET /organizations/{organizationId}/shopper-context/{usid} 403 response._ ### DELETE deleteShopperContext `DELETE /organizations/{organizationId}/shopper-context/{usid}` Operation ID: `deleteShopperContext`. Security: ShopperToken (sfcc.shopper-context.rw); ShopperClientContextToken (sfcc.shopper-context.rw). Delete the shopper's context based on the shopperJWT. #### Parameters * `usid` (path, string, required) 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. * `organizationId` (path, OrganizationId, required) 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 ``` * `siteId` (query, SiteId, required) The site context. _Example_ ``` RefArch ``` * `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken. Example: `550e8400-e29b-41d4-a716-446655440000`. #### Responses * **204** The shopper's context was deleted successfully. * **400** The usid in the incoming request does not match the usid in the token. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getShopperContext400: same as GET /organizations/{organizationId}/shopper-context/{usid} 400 response._ * **401** Your shopper JWT is invalid and cannot be used to identify the API client. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getShopperContext401: same as GET /organizations/{organizationId}/shopper-context/{usid} 401 response._ * **403** Your shopper JWT is valid, but you do not have permission to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example Forbidden: same as GET /organizations/{organizationId}/shopper-context/{usid} 403 response._ * **404** Shopper Context for ORGANIZATION\_ID - f\_ecom\_bhbv\_prd and USID - 7e1f65fb-185c-4788-8cec-05fef8dac77d not found in repository. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getShopperContext404: same as GET /organizations/{organizationId}/shopper-context/{usid} 404 response._ ### PATCH Update an existing shopper's context based on the Shopper JWT. `PATCH /organizations/{organizationId}/shopper-context/{usid}` Operation ID: `updateShopperContext`. Security: ShopperToken (sfcc.shopper-context.rw); ShopperClientContextToken (sfcc.shopper-context.rw). If the shopper context exists, it's updated with the patch body. * If a new attribute that does not exist in the existing shopper context is present, it is added to the context. -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: * `custom qualifiers` or `assignment qualifiers`: If the individual qualifier key exists, it is overwritten with the new value. If the value of the key is set to null, it is deleted from the existing shopper context. If an empty `custom qualifiers` or `assignment qualifiers` object `{}` is passed, the entire qualifier object is deleted. * `effectiveDateTime` or `sourceCode` or `clientIp`: If the new value is set to an empty string (""), it is deleted from the existing shopper context. If the new value is set to null, it is ignored. If the new value is not empty or null, it overwrites the existing value. * `customerGroupIds`: If a list of `customerGroupIds` exists, it is replaced by the new list of customer group IDs from the request. If `customerGroupIds` is set to an empty array \[\], the existing list in the shopper context is deleted. * `geoLocation`: If it exists, the entire `geoLocation` object is replaced with the new value. If the new value is set to null, it is ignored. If an empty `geoLocation` object `{}` is passed, it is deleted. #### Parameters * `usid` (path, string, required) 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. * `organizationId` (path, OrganizationId, required) 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 ``` * `siteId` (query, SiteId, required) The site context. _Example_ ``` RefArch ``` * `evaluateContextWithClientIp` (query, boolean) Determines whether to evaluate the context using the provided `clientIp`. This property is available with B2C Commerce version 24.7. * If `evaluateContextWithClientIp` is set to `true`: * The `clientIP` is saved and used in subsequent requests. * If `evaluateContextWithClientIp` is set to `false`: * The `clientIP` is not saved and will not be used in subsequent requests. * `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken. Example: `550e8400-e29b-41d4-a716-446655440000`. #### Request body (required) Media type: `application/json`. Schema: `ShopperContext`. _Example: ShopperContextUpdateRequestBody_ ``` { "effectiveDateTime": null, "customQualifiers": { "deviceType": "iPad", "operatingSystem": null, "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" ] } ``` #### Responses * **200** The shopper context was updated successfully. Headers: * `X-Geolocation` (string) Media type: `application/json`. Schema: `ShopperContext`. _Example: ShopperContextUpdateResponseExample_ ``` { "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" ] } ``` * **400** The usid in the incoming request does not match the usid in the token. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example updateShopperContext400: same as GET /organizations/{organizationId}/shopper-context/{usid} 400 response._ * **401** Your shopper JWT is invalid and cannot be used to identify the API client. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example updateShopperContext401: same as GET /organizations/{organizationId}/shopper-context/{usid} 401 response._ * **403** Your shopper JWT is valid, but you do not have permission to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example updateShopperContext403: same as GET /organizations/{organizationId}/shopper-context/{usid} 403 response._ ## Schemas ### OrganizationId 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). Type: `string`. Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`. ### SiteId 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 Type: `string`. Minimum length: 1. Maximum length: 32. Example: `RefArch`. ### ShopperContext A shoppers' context represented as key-value string pairs. * `effectiveDateTime` (_string (date-time)_, nullable) 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` (_string_, nullable) 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` (_array of string_) 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: Maximum length: 256. Example: `BigSpenders`. * `customQualifiers` (_object_) 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). Additional properties: `string`. _Example_ ``` { "deviceType": "mobile", "ipAddress": "189.0.0.0", "operatingSystem": "Android" } ``` * `assignmentQualifiers` (_object_) 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). Additional properties: `string`. _Example_ ``` { "store": "boston" } ``` * `clientIp` (_string_) 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. When `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. However, 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. The query parameter `evaluateContextWithClientIp` determines whether to evaluate the context using the provided `clientIp`. * If `evaluateContextWithClientIp` is set to `true`: * The `clientIp` is saved and used in subsequent requests. Note: If `geoLocation` is also saved in the context, it takes precedence over the `clientIp`. * If `evaluateContextWithClientIp` is set to `false`: * The `clientIp` is not saved and is not used in subsequent requests. Example: `12.12.12.1`. * `geoLocation` (_object_) 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. * `city` (_string_) The city name associated with this location. Example: `Boston`. * `country` (_string_) The country name associated with this location. Example: `United States of America`. * `countryCode` (_string_) The ISO country code associated with this location. Example: `US`. * `latitude` (_number (double)_) The latitude coordinate, which is a number between -90.0 and +90.0, associated with this location. Example: `10.11`. * `longitude` (_number (double)_) The longitude coordinate, which is a number between -180.0 and +180.0, associated with this location. Example: `198.34`. * `metroCode` (_string_) The metro code associated with this location. * `postalCode` (_string_) The postal code associated with this location. Example: `01730`. * `region` (_string_) The region (subdivision) name for this location. Corresponds with "state" in the USA. Example: `NA`. * `regionCode` (_string_) The region (province or state) code for this location. Example: `12345`. * `couponCodes` (_array of string_) 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: Maximum length: 256. Example: `SAVE20`. _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" ] } ``` ### ErrorResponse * `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization Maximum length: 256. Example: `You do not have enough credit`. * `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `NotEnoughMoney`. * `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem. Example: `Your current balance is 30, but that costs 50`. * `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `/account/12345/msgs/abc`.