Sample Flow: Authorizing Guest Users and Calling Commerce APIs

Once the external client app is set up and you have the consumer details, including Consumer Key and Consumer Secret, you’re ready to use the Headless Guest Flow. Issue identifiers in the form of unique visitor IDs (UVIDs) for these unknown visitors with the Headless Guest Flow. See Headless Identity APIs: Headless Guest Flow for Public Clients for more information.

Request Authorization Code for the Guest User

Authorization

The first step is to authorize the guest user. The following is an example of an authorization request.

Endpoint: (POST) https://<domain>.site.com/<site ID>/services/oauth2/authorize

Request

Header:

1Uvid-Hint: UVID abcd-1234-efgh
2Auth-Request-Type: guest

Body:

1response_type=code_credentials&
2client_id=***********&
3redirect_uri=https://www.MyExperienceCloudSite.my.site.com/services/oauth2/echo&
4code_challenge=********&
5scope=openid

Response

Salesforce validates the UVID and authorizes the guest user. If the UVID was passed as a JWT-based access token, Salesforce checks the validity of the token. The API returns the code response with the authorization and other parameters.

1{
2  "code": "aPrxhgBwK8L6...",
3  "state": "optional_state_parameter"
4}

Token Exchange (Tokenization)

After authorization is complete, exchange the authorization code for a JWT access token.

Header:

1Uvid-Hint: UVID abcd-1234-efgh
2Auth-Request-Type: guest

Note: For guest user authentication flows, include the Uvid-Hint and Auth-Request-Type guest headers in the token request. Requests that omit these headers can return an unknown_error response.

Endpoint: (POST) https://<domain>.site.com/<site ID>/services/oauth2/token

Request

Body:

1grant_type=authorization_code
2code={AUTHORIZATION_CODE} /*Received using the Authorize POST request*/
3client_id={CONSUMER_KEY}
4client_secret={CONSUMER_SECRET}
5redirect_uri={CALLBACK_URL}

Response

Your app processes the access token response and creates a guest session, persisting the UVID value.

1{
2  "access_token": "00D5g000000xxxx!AQwAQH...",
3  "token_format": "jwt",
4  "token_type": "Bearer"
5}

Use Commerce APIs

Use the JWT token to interact with Commerce APIs.

Create Cart

Endpoint: (POST) https://<domain>.site.com/<site ID>/services/data/vXX.X/commerce/webstores/{webstoreId}/carts?currencyIsoCode=USD&language=en-US&asGuest=true&htmlEncode=false

See Commerce Webstore, Create Cart for more information.

Add Items to Cart

Endpoint: (POST) https://<domain>.site.com/<site ID>/services/data/vXX.X/commerce/webstores/{webstoreId}/carts/{cartId}/cart-items?currencyIsoCode=USD&language=en-US&asGuest=true&htmlEncode=false

See Commerce Webstore, Add Items to Cart for more information.

Checkout Flow

Start Checkout:

Endpoint: (POST) https://<domain>.site.com/<site ID>/services/data/vXX.X/commerce/webstores/{webstoreId}/carts/{cartId}/checkouts?currencyIsoCode=USD&language=en-US&asGuest=true&htmlEncode=false

To continue with the checkout process, choose the Checkout API that best fits your implementation requirements:

Commerce Webstore, Checkout Orders—Single-step order placement.
Commerce Webstore Checkout, Place Order Action—Two-step process: Prepare and Submit.