--- schema_version: "1" id: f9a349baf8bfb7eb51f9e3992e5acee2d310887aa01ef2ac4c37ed36f5e4de90 title: Shopper Agents 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-agents.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-agents source_site: developer.salesforce.com content_type: documentation content_hash: f8f00274289c065b31cd3b5675385028d794b833bfc2c0918d9a0930f582fdb1 products: - B2C Commerce API - Salesforce APIs --- Shopper Agents # Shopper Agents [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-agents/shopper-agents-oas-v1-public.yaml) ## API Overview This REST API initializes an Agentforce session when a new session starts. ### Authentication & Authorization The Shopper Agent API requires a shopper access token from the Shopper Login and API Access Service (SLAS). You must include the relevant scope(s) in the client ID used to generate the SLAS token. * `sfcc.shopper-agents.rw`: Required for initializing shopper agent session (POST operations). For 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) 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. ### Use Cases #### Shopper Agent Initialization When a new agentic session starts, you receive a session initialization key. Include that key in the request to initialize the Agentforce session. **Flow:** 1. Obtain a `sessionInitKey` from a supported service. 2. Initialize an agent session using the previously obtained `sessionInitKey`. #### sessionInitKey `sessionInitKey` is the session initialization identifier that is obtained when an Agentforce session starts. The request body must include the `sessionInitKey` field. Missing or invalid `sessionInitKey` results in `INVALID_REQUEST_PARAMETERS` (400). **Version:** 1.1.5 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/shopper/shopper-agents/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 B2C Commerce Shopper API endpoints. * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token) * Scope sfcc.shopper-agents.rw: Allows read/write operations on shopper agents. * 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-agents.rw: Allows read/write operations on shopper agents * `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-agents.rw: Allows read/write operations on shopper agents. ## Operations ### POST Initializes an Agentforce session. `POST /organizations/{organizationId}/session/init` Operation ID: `postSessionInit`. Security: ShopperToken (sfcc.shopper-agents.rw); ShopperClientContextToken (sfcc.shopper-agents.rw). The request body must include the sessionInitKey field. Missing or invalid sessionInitKey information results in INVALID\_REQUEST\_PARAMETERS (400). #### Parameters * `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 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: SiteId_ ``` 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`. * `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application. #### Request body (required) Media type: `application/json`. Schema: `SessionInitRequest`. _Example: ShopperAgentsSessionInitRequest_ ``` { "sessionInitKey": "aPrx.0rn0R1k7G.PtUUXh6S90_rMvqsYhpDZlNpyYsLsTm8KYLodM3flsRBbCD" } ``` #### Responses * **202** Accepted (initialization successful; no response body) * **400** Validation Error Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ValidationError_ ``` { "title": "Validation Error", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation", "detail": "Unable to validate post body." } ``` * **401** Unauthorized (invalid or expired token) Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: Unauthorized_ ``` { "title": "Invalid Basic Authentication", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "detail": "Your access token is invalid or expired and can’t be used to identify a user." } ``` * **500** Unexpected server-side exception during SLAS authentication Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ReadError_ ``` { "title": "Internal Server Error", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/internal-server-error", "detail": "Unexpected server-side exception during SLAS authentication." } ``` ## 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`. ### SessionInitRequest * `sessionInitKey` (_string_) The session initialization key that is is obtained when beginning an Agentforce session, and is then used to initialize the session. Minimum length: 1. Maximum length: 256. Example: `aPrx.0rn0R1k7G.PtUUXh6S90_rMvqsYhpDZlNpyYsLsTm8KYLodM3flsRBbCD`. ### 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`.