Salesforce Commerce Cloud

Before writing any FlutterFlow or Cloud Function code, you need four pieces of information from your Salesforce Commerce Cloud environment. These are available in SFCC Business Manager and from your Salesforce partner or admin. First: your Organization ID — a string that looks like f_ecom_XXXX_XXX and identifies your SFCC org. Second: your Shortcode — a short alphanumeric string that forms part of the SCAPI base URL (your SCAPI base will be https://{shortcode}.api.commercecloud.salesforce.com). Third: your SLAS Client ID — registered in Business Manager under Administration → SLAS Administration → Client Registry. Fourth: your Site ID — the specific storefront site within your org (e.g. RefArch or your custom site ID). If you're using PKCE guest flow only (no registered shopper login), you do NOT need a client secret. If you're building a registered shopper flow, you'll also need the client secret — store this in Firebase Functions environment variables, never in FlutterFlow. Verify your SLAS client is configured with the correct redirect URI for the Cloud Function — for guest PKCE, this can be any HTTPS URL since there's no browser redirect in the server-side flow. Double-check that the required API scopes (sfcc.shopper-products.rw, sfcc.shopper-baskets-orders.rw, etc.) are granted to your SLAS client. These configuration steps happen entirely in SFCC Business Manager and Salesforce's identity management — no FlutterFlow or Firebase work yet.

The SLAS OAuth flow involves generating a PKCE code verifier and challenge, calling the SLAS authorize endpoint, exchanging the authorization code for a token, and managing token expiry and refresh. None of this can happen in a Flutter client — PKCE code verifiers that reach the client can be intercepted, and any client secret would be exposed in the app binary. Create a Firebase Cloud Function with two HTTP endpoints: one to issue a guest shopper token (/guestToken), and one to refresh an existing token (/refreshToken). Deploy the function with your SFCC credentials set as environment variables in the Firebase Console under Functions → Configuration: SFCC_ORG_ID, SFCC_SHORTCODE, SFCC_SITE_ID, SFCC_CLIENT_ID, and (if using registered shopper flow) SFCC_CLIENT_SECRET. The guestToken endpoint runs the full PKCE guest shopper flow and returns a JSON response to FlutterFlow containing just the access_token and its expires_in seconds. FlutterFlow stores this token in App State and passes it as a Bearer header to all SCAPI calls. The refreshToken endpoint accepts an existing refresh token and returns a new access token — FlutterFlow calls this when the current token is close to expiry or when a SCAPI call returns 401. Test the deployed function by calling the /guestToken endpoint directly in your browser or a REST client — you should receive a JSON response with an access_token field. Copy this token and use it to manually test a SCAPI product search call to confirm it works before wiring up FlutterFlow.

1const functions = require('firebase-functions');
2const axios = require('axios');
3const crypto = require('crypto');
4
5const ORG_ID    = process.env.SFCC_ORG_ID;      // e.g. f_ecom_XXXX_XXX
6const SHORTCODE = process.env.SFCC_SHORTCODE;    // e.g. kv7kzm78
7const SITE_ID   = process.env.SFCC_SITE_ID;      // e.g. RefArch
8const CLIENT_ID = process.env.SFCC_CLIENT_ID;
9
10const SLAS_BASE = `https://${SHORTCODE}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/${ORG_ID}`;
11
12function generatePKCE() {
13  const verifier = crypto.randomBytes(32).toString('base64url');
14  const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
15  return { verifier, challenge };
16}
17
18exports.sfccGuestToken = functions.https.onRequest(async (req, res) => {
19  res.set('Access-Control-Allow-Origin', '*');
20  res.set('Access-Control-Allow-Methods', 'GET, OPTIONS');
21  if (req.method === 'OPTIONS') { res.status(204).send(''); return; }
22
23  try {
24    const { verifier, challenge } = generatePKCE();
25    // Step 1: Get authorization code
26    const authResp = await axios.get(`${SLAS_BASE}/oauth2/authorize`, {
27      params: {
28        client_id: CLIENT_ID,
29        channel_id: SITE_ID,
30        redirect_uri: 'http://localhost:3000/callback',
31        response_type: 'code',
32        code_challenge: challenge,
33        code_challenge_method: 'S256',
34        hint: 'guest',
35      },
36      maxRedirects: 0,
37      validateStatus: s => s === 303 || s === 302,
38    });
39    const location = authResp.headers['location'];
40    const code = new URL(location, 'https://placeholder').searchParams.get('code');
41
42    // Step 2: Exchange code for token
43    const tokenResp = await axios.post(
44      `${SLAS_BASE}/oauth2/token`,
45      new URLSearchParams({
46        grant_type: 'authorization_code_pkce',
47        code,
48        redirect_uri: 'http://localhost:3000/callback',
49        code_verifier: verifier,
50        client_id: CLIENT_ID,
51        channel_id: SITE_ID,
52      }),
53      { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }
54    );
55    res.status(200).json({
56      access_token: tokenResp.data.access_token,
57      refresh_token: tokenResp.data.refresh_token,
58      expires_in: tokenResp.data.expires_in,
59    });
60  } catch (error) {
61    res.status(500).json({ error: error.message });
62  }
63});
64
65exports.sfccRefreshToken = functions.https.onRequest(async (req, res) => {
66  res.set('Access-Control-Allow-Origin', '*');
67  if (req.method === 'OPTIONS') { res.status(204).send(''); return; }
68  const { refresh_token } = req.body;
69  try {
70    const tokenResp = await axios.post(
71      `${SLAS_BASE}/oauth2/token`,
72      new URLSearchParams({
73        grant_type: 'refresh_token',
74        refresh_token,
75        client_id: CLIENT_ID,
76      }),
77      { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }
78    );
79    res.status(200).json({
80      access_token: tokenResp.data.access_token,
81      expires_in: tokenResp.data.expires_in,
82    });
83  } catch (error) {
84    res.status(401).json({ error: 'Token refresh failed' });
85  }
86});
87

With the Cloud Functions deployed, set up two separate API Groups in FlutterFlow to handle the two tiers of the architecture: one for token management via the Cloud Functions, and one for SCAPI Shopper product and search calls. In FlutterFlow, click API Calls in the left nav → + Add → Create API Group. Name it SFCCAuth. Set the Base URL to your Cloud Function base URL (e.g. https://us-central1-your-project.cloudfunctions.net). Add one API Call named GetGuestToken: method GET, endpoint /sfccGuestToken, no headers needed. Add a second API Call named RefreshToken: method POST, endpoint /sfccRefreshToken, Content-Type: application/json header, and a JSON body variable for refresh_token. Create a second API Group named SFCCShop. Set the Base URL to your SCAPI endpoint: https://{shortcode}.api.commercecloud.salesforce.com/commerce/shopper-products/v1 — replace {shortcode} with your actual shortcode value as a hardcoded string (not a variable, since it doesn't change). Add a Group-level header: Authorization with value Bearer {{accessToken}} where accessToken is a variable. Add these API Calls: - SearchProducts: GET /organizations/{{orgId}}/product-search — query parameters: q (search term), limit (20), site_id (your site ID) - GetProductDetail: GET /organizations/{{orgId}}/products/{{productId}} — path variables: orgId, productId; query parameter: site_id In the Response & Test tab for SearchProducts, paste a sample SCAPI search response and click Generate JSON Paths. SCAPI product search responses have a nested structure: $.hits[0].productId, $.hits[0].productName, $.hits[0].price, $.hits[0].image.link — map these carefully as SCAPI's schema differs from simpler REST APIs.

1{
2  "API Group SFCCAuth": {
3    "Base URL": "https://us-central1-YOUR_PROJECT.cloudfunctions.net",
4    "Calls": [
5      { "Name": "GetGuestToken", "Method": "GET",  "Endpoint": "/sfccGuestToken" },
6      { "Name": "RefreshToken",  "Method": "POST", "Endpoint": "/sfccRefreshToken",
7        "Headers": { "Content-Type": "application/json" },
8        "Body": { "refresh_token": "{{refreshToken}}" } }
9    ]
10  },
11  "API Group SFCCShop": {
12    "Base URL": "https://YOUR_SHORTCODE.api.commercecloud.salesforce.com/commerce/shopper-products/v1",
13    "Group Headers": { "Authorization": "Bearer {{accessToken}}" },
14    "Calls": [
15      {
16        "Name": "SearchProducts",
17        "Method": "GET",
18        "Endpoint": "/organizations/{{orgId}}/product-search",
19        "Query Params": [
20          { "name": "q",       "type": "String" },
21          { "name": "limit",   "default": "20" },
22          { "name": "site_id", "default": "YOUR_SITE_ID" }
23        ]
24      },
25      {
26        "Name": "GetProductDetail",
27        "Method": "GET",
28        "Endpoint": "/organizations/{{orgId}}/products/{{productId}}",
29        "Query Params": [
30          { "name": "site_id", "default": "YOUR_SITE_ID" }
31        ]
32      }
33    ]
34  }
35}
36

Short-lived shopper tokens are the trickiest part of SFCC in FlutterFlow. The guest token typically expires after 30 minutes (verify in your SLAS configuration), which means a user session lasting longer than that will encounter 401 errors mid-flow — usually at the worst possible moment, such as when adding to basket or initiating checkout. Set up App State variables to manage token lifecycle. In FlutterFlow, click App State in the left nav → + Add State Variable. Create three variables: accessToken (String), refreshToken (String), and tokenExpiry (Integer — Unix timestamp of when the current token expires). On your app's initial page, add an On Page Load Action that calls SFCCAuth → GetGuestToken. In the Action Flow, after a successful response, use Update App State to set accessToken from the response JSON Path $.access_token, refreshToken from $.refresh_token, and tokenExpiry from the current timestamp plus the $.expires_in value (in seconds). Before any SCAPI API Call that touches basket or checkout (which are most sensitive to 401), add a conditional check in the Action Flow: if the current timestamp is within 300 seconds of tokenExpiry, first call SFCCAuth → RefreshToken (passing the current refreshToken App State value), update accessToken and tokenExpiry from the response, then proceed with the SCAPI call. This ensures the token is always valid when it reaches SCAPI. For the SCAPI API Calls, always pass the accessToken App State variable as the accessToken variable in the API Group. The API Group's Authorization header is already set to Bearer {{accessToken}}, so it picks up the current value automatically — you do not need to set the header manually on each call.

Create a ProductSearch page in FlutterFlow. Add a TextField at the top bound to a searchQuery page state variable (String). Add a Search button — in its Action Flow, fire SFCCShop → SearchProducts with q set to the searchQuery variable, orgId from App Values set to your SFCC org ID, and accessToken from App State. Below the search bar, add a ListView. Bind it via Backend Query to SFCCShop → SearchProducts (with a default empty search on page load to show featured products). The SCAPI search response nests hits inside a top-level object — use JSON Path $.hits to get the array. Create a FlutterFlow Data Type called SFCCProductHit with fields: productId (String), productName (String), price (Double), imageLink (String), pageUrl (String). Map the search response JSON Paths: $.hits[0].productId, $.hits[0].productName, $.hits[0].price, $.hits[0].image.link. For the Product Detail page, pass the productId when navigating from the search results (use Navigate action with a parameter). On the detail page, fire SFCCShop → GetProductDetail on page load. The detail response schema is different from the search hit schema — create a separate Data Type SFCCProductDetail with fields: id (String), name (String), longDescription (String), price (Double), primaryImageLink (String), availableColors (List of String). Map the JSON Paths from the actual SCAPI product detail response structure (check the Response & Test panel for the exact paths your org returns). For basket management, note that the Shopper Baskets SCAPI endpoint is at a different API path (/commerce/shopper-baskets/v1) — create a third API Group SFCCBasket for those calls. Basket operations (create, add item, get) require the same accessToken and use the org ID and site ID the same way.

Even with proactive token refresh logic (Step 4), edge cases can cause 401 errors from SCAPI — for example, if the app is backgrounded for a long time and the token expires while the app is inactive. Set up a global error handler for SCAPI API Calls that detects 401 responses and triggers a token refresh automatically. In FlutterFlow, for each SCAPI API Call, go to the On Error section of the Backend Query or Action. Add a conditional action: if the error code equals 401, run the RefreshToken API Call (SFCCAuth → RefreshToken), update App State with the new accessToken and tokenExpiry, then retry the original SCAPI call. This retry loop should only execute once — use a retrying Boolean App State variable to prevent infinite 401 loops if the refresh itself fails. For the basket and checkout flow, SCAPI's Shopper Baskets endpoint (/commerce/shopper-baskets/v1/organizations/{orgId}/baskets) requires a POST to create a basket and returns a basket ID that must be stored in App State. Add a basketId App State variable (String) and set it when the user first adds an item to the basket. All subsequent basket operations (add item, update quantity, apply promo, retrieve) require this basket ID as a path segment. Test the full session flow: open the app, browse products, add to basket, close and reopen the app after 30+ minutes, and verify the token refresh happens transparently and the basket persists. SCAPI guest baskets may not persist across sessions without a registered shopper token — test this behavior on your specific SFCC org configuration and decide whether to require login before basket creation.