Salesforce Commerce Cloud

Before touching Bubble, gather the SFCC credentials you need from your Salesforce Business Manager instance. Log in to Business Manager (your org's admin console). The following values are required: (1) Organization ID — found in Business Manager under Administration → Salesforce Commerce Cloud API Client → your client record, or in merchant tooling documentation; (2) Shortcode — the alphanumeric string that appears in your SCAPI base URL; it is typically visible in Business Manager under Administration → API Configuration or in your org's onboarding documentation; (3) Site ID — the identifier for your specific storefront site within the SFCC org (e.g., 'RefArch' for reference architecture sites, or a custom name); (4) SLAS Client ID — created in Business Manager under Administration → SLAS Administration → API Clients. When creating a SLAS API client, set the token TTL (how long tokens last — typically 1800 seconds = 30 minutes) and note whether you are using the guest (unauthenticated shopper) or registered (authenticated shopper) flow. For headless storefront builds, the guest flow is the starting point. The SLAS client may also have a client secret for registered shopper flows — if so, store it securely. Important upfront disclosure: if you are reading this tutorial without an active SFCC contract or partner sandbox, the integration cannot be completed. SFCC has no sandbox signup, no developer tier, and no API access outside of a commercial or partner relationship.

1// SFCC Base URL format — your shortcode goes where {shortcode} appears
2// Example: if shortcode is 'abc123', your base URL is:
3https://abc123.api.commercecloud.salesforce.com
4
5// Key SFCC configuration values you need to collect:
6// org_id:     your org identifier (from Business Manager → Administration)
7// shortcode:  alphanumeric prefix in SCAPI base URL
8// site_id:    your storefront site identifier (e.g., RefArch)
9// slas_client_id: from Business Manager → Administration → SLAS Administration → API Clients
10
11// Wrong shortcode = network error or 404, NOT a 401
12// Verify shortcode before any API testing

This step requires deploying a server-side function outside of Bubble. SFCC's SLAS system uses PKCE OAuth, and Bubble cannot generate PKCE code_verifier/code_challenge pairs or hold SLAS credentials securely. A Firebase Cloud Function is the most accessible choice for most teams — it requires a Firebase project (free Spark plan is sufficient for the function; just billing must be enabled). Create a Firebase project at console.firebase.google.com. In the project, go to Functions and set up a new function using the Firebase CLI on your computer. The function needs two endpoints: (1) sfccGuestToken — takes no parameters, runs the SLAS PKCE guest-shopper flow (generate code_verifier, derive code_challenge, POST to SLAS token endpoint with the PKCE values), and returns only the access_token and its expiry; (2) sfccRefreshToken — takes the current refresh_token, calls SLAS token refresh, and returns the new access_token and refresh_token. Store all SLAS credentials (client_id, org_id, site_id, shortcode) in Firebase environment config or Cloud Secrets — never hardcode them in the function. The SLAS token endpoint is: https://{shortcode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{org_id}/oauth2/token. Deploy the function with Firebase deploy --only functions. Note the function's HTTPS URL — you will use it in Bubble's API Connector as the auth proxy endpoint. If your team prefers Cloudflare Workers over Firebase, the same logic applies: a Worker holds credentials and serves the same two endpoints.

1// Firebase Cloud Function — SLAS Guest Token Minting
2// File: functions/index.js
3// Deploy with: firebase deploy --only functions
4
5const functions = require('firebase-functions');
6const axios = require('axios');
7const crypto = require('crypto');
8
9// Store these in Firebase config: firebase functions:config:set sfcc.client_id=... etc.
10const SFCC_CLIENT_ID = functions.config().sfcc.client_id;
11const SFCC_ORG_ID = functions.config().sfcc.org_id;
12const SFCC_SITE_ID = functions.config().sfcc.site_id;
13const SFCC_SHORTCODE = functions.config().sfcc.shortcode;
14
15function base64URLEncode(buffer) {
16  return buffer.toString('base64')
17    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
18}
19
20exports.sfccGuestToken = functions.https.onRequest(async (req, res) => {
21  res.set('Access-Control-Allow-Origin', '*');
22  if (req.method === 'OPTIONS') { res.status(204).send(''); return; }
23  try {
24    const code_verifier = base64URLEncode(crypto.randomBytes(32));
25    const code_challenge = base64URLEncode(
26      crypto.createHash('sha256').update(code_verifier).digest()
27    );
28    const tokenURL = `https://${SFCC_SHORTCODE}.api.commercecloud.salesforce.com` +
29      `/shopper/auth/v1/organizations/${SFCC_ORG_ID}/oauth2/token`;
30    const params = new URLSearchParams({
31      grant_type: 'client_credentials',
32      client_id: SFCC_CLIENT_ID,
33      redirect_uri: 'http://localhost',
34      code_verifier,
35      code_challenge,
36      code_challenge_method: 'S256',
37      channel_id: SFCC_SITE_ID,
38      hint: 'guest'
39    });
40    const response = await axios.post(tokenURL, params.toString(), {
41      headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
42    });
43    res.json({
44      access_token: response.data.access_token,
45      refresh_token: response.data.refresh_token,
46      expires_in: response.data.expires_in
47    });
48  } catch (error) {
49    res.status(500).json({ error: error.message });
50  }
51});
52
53exports.sfccRefreshToken = functions.https.onRequest(async (req, res) => {
54  res.set('Access-Control-Allow-Origin', '*');
55  if (req.method === 'OPTIONS') { res.status(204).send(''); return; }
56  const { refresh_token } = req.body;
57  try {
58    const tokenURL = `https://${SFCC_SHORTCODE}.api.commercecloud.salesforce.com` +
59      `/shopper/auth/v1/organizations/${SFCC_ORG_ID}/oauth2/token`;
60    const params = new URLSearchParams({
61      grant_type: 'refresh_token',
62      refresh_token,
63      client_id: SFCC_CLIENT_ID
64    });
65    const response = await axios.post(tokenURL, params.toString(), {
66      headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
67    });
68    res.json({
69      access_token: response.data.access_token,
70      refresh_token: response.data.refresh_token,
71      expires_in: response.data.expires_in
72    });
73  } catch (error) {
74    res.status(500).json({ error: error.message });
75  }
76});

With the Cloud Function deployed and returning tokens, set up Bubble's API Connector with two groups. Open your Bubble app editor, go to Plugins tab → Add plugins → search 'API Connector' (published by Bubble) and install it. Group 1 — SFCCAuth: Click 'Add another API', name it 'SFCCAuth'. Set the root URL to your Firebase Cloud Function base URL (e.g., https://us-central1-yourproject.cloudfunctions.net). No shared headers needed — the function handles its own auth internally. Add one call: name it 'Get Guest Token', method POST, path /sfccGuestToken, no body parameters. Set the call's 'Use as' to 'Action'. Click 'Initialize call' — it should return the access_token, refresh_token, and expires_in fields. Group 2 — SFCCShop: Click 'Add another API', name it 'SFCCShop'. Set the root URL to https://{shortcode}.api.commercecloud.salesforce.com (replace shortcode with your actual shortcode). Add shared headers: Authorization with value 'Bearer [accessToken]' (check Private checkbox) where accessToken is a dynamic group-level parameter. Add an Accept: application/json header. This group will hold all your SCAPI Shopper API calls — product search, product detail, basket operations. The accessToken parameter will be supplied by your Bubble workflows from the stored SFCCSession token.

1// Group 1: SFCCAuth — points at Firebase Cloud Function
2{
3  "groupName": "SFCCAuth",
4  "rootURL": "https://us-central1-YOUR-FIREBASE-PROJECT.cloudfunctions.net",
5  "sharedHeaders": [],
6  "calls": [
7    {
8      "name": "Get Guest Token",
9      "method": "POST",
10      "path": "/sfccGuestToken",
11      "useAs": "Action"
12    },
13    {
14      "name": "Refresh Token",
15      "method": "POST",
16      "path": "/sfccRefreshToken",
17      "useAs": "Action",
18      "bodyParams": [{ "name": "refresh_token", "dynamic": true }]
19    }
20  ]
21}
22
23// Group 2: SFCCShop — points at SCAPI Shopper endpoints
24{
25  "groupName": "SFCCShop",
26  "rootURL": "https://YOUR-SHORTCODE.api.commercecloud.salesforce.com",
27  "sharedHeaders": [
28    {
29      "name": "Authorization",
30      "value": "Bearer <accessToken dynamic>",
31      "private": true
32    },
33    {
34      "name": "Accept",
35      "value": "application/json",
36      "private": false
37    }
38  ],
39  "groupParameters": [
40    { "name": "accessToken", "description": "SLAS Bearer token from SFCCSession record" }
41  ]
42}

Create a Bubble data type to manage the SLAS token lifecycle. Go to Data tab → Data types → Add a type named 'SFCCSession'. Add fields: access_token (text), refresh_token (text), token_expiry (date), user (User — optional, for multi-user apps). Apply privacy rules to this data type immediately: Data tab → Privacy → SFCCSession → set rule so that only the Current User who owns the record can read it. Create a Backend Workflow named 'SFCC_InitSession'. This workflow calls the SFCCAuth 'Get Guest Token' action, then creates or modifies an SFCCSession record: set access_token to the call's returned access_token value, set refresh_token to the returned refresh_token, set token_expiry to current date/time + the returned expires_in value in seconds (typically 1800 seconds). Trigger this workflow when your app loads for a new session — use the page's 'On page load' workflow to check if an SFCCSession record exists for the current user. If not, schedule the SFCC_InitSession Backend Workflow. For the refresh workflow, create 'SFCC_RefreshSession' that calls the SFCCAuth 'Refresh Token' action with the current user's stored refresh_token, then updates the SFCCSession record with the new access_token, refresh_token, and a new token_expiry. Set up a Recurring Backend Workflow (Settings → Backend Workflows → Recurring events) running every 25 minutes: it searches for SFCCSession records where token_expiry is within the next 5 minutes and calls SFCC_RefreshSession for each one. Recurring Backend Workflows are available on paid Bubble plans only.

1// SFCCSession data type fields:
2// access_token  (text) — current SLAS Bearer token for API calls
3// refresh_token (text) — used to obtain new access_token when it expires
4// token_expiry  (date) — timestamp when access_token will expire (~30 min from issue)
5// user          (User) — links this session to a specific Bubble User (optional)
6
7// Privacy rules to add immediately (Data tab → Privacy → SFCCSession):
8// Rule: When Current User is This SFCCSession's user → allow read/modify
9// This prevents any user from reading another user's SFCC token
10
11// Token expiry calculation:
12// expires_in from SLAS response = 1800 (seconds, typically)
13// token_expiry = Current Date/Time + 1800 seconds
14// Bubble expression: Current date/time + 1800 seconds
15
16// Recurring Backend Workflow logic (every 25 minutes):
17// Search SFCCSession where token_expiry < Current date/time + 5 minutes
18// For each result: call SFCC_RefreshSession with that record's refresh_token

Add SCAPI Shopper endpoints to the SFCCShop API Connector group. SCAPI product search and product detail have different JSON schemas and must be defined as separate calls. Add call 1: 'Product Search' — GET to /commerce/shopper-products/v1/organizations/{orgId}/product-search. Add parameters: orgId (static — your org ID), siteId (static — your site ID), q (search query text, dynamic), limit (results per page, default 25), offset (for pagination). To initialize, use a real access_token from your SFCCSession record and a search query that will return results. SCAPI product search nests results in a 'hits' array. Each hit contains: productId, productName, price, imageGroups, and other fields. Bubble will detect 'hits first item's productId', 'hits first item's productName', etc. Add call 2: 'Product Detail' — GET to /commerce/shopper-products/v1/organizations/{orgId}/products/{productId}. Parameters: orgId (static), siteId (static), productId (dynamic). The product detail response has a completely different schema from search hits: it uses 'id', 'name', 'longDescription', 'price', 'stepQuantity', and 'variants' (for variant products). Initialize this call separately with a specific product ID. Use the 'hits first item's productId' from a search result as the test value. Both calls require the accessToken group parameter — when initializing, paste the current token from your SFCCSession record into the accessToken parameter field. Build a product search page in Bubble: add a Search Input element, wire its value to the 'q' parameter of a Product Search API call, display results in a Repeating Group, and implement product detail navigation using the productId from search hits.

1// SCAPI Product Search response structure (partial)
2{
3  "limit": 25,
4  "hits": [
5    {
6      "productId": "25592581M",
7      "productName": "Striped Silk Tie",
8      "price": 68.00,
9      "priceMax": 78.00,
10      "currency": "USD",
11      "representedProduct": { "id": "25592581M" },
12      "imageGroups": [
13        {
14          "viewType": "large",
15          "images": [
16            { "alt": "Silk Tie", "link": "https://...image.jpg", "title": "Silk Tie" }
17          ]
18        }
19      ]
20    }
21  ],
22  "offset": 0,
23  "total": 47
24}
25
26// SCAPI Product Detail response structure (DIFFERENT schema from search hits)
27{
28  "id": "25592581M",
29  "name": "Striped Silk Tie",
30  "longDescription": "<p>Premium Italian silk...</p>",
31  "price": 68.00,
32  "currency": "USD",
33  "variants": [
34    { "productId": "25592581M-RED", "price": 68.00, "orderable": true, "variationValues": { "color": "RED" } }
35  ],
36  "imageGroups": [ ... ]
37}
38
39// Note: product search uses 'productId' and 'productName' (camelCase)
40// Product detail uses 'id' and 'name' — different field names for the same concepts

SCAPI basket management (cart) uses a separate API path. Add a third call group or additional calls to SFCCShop for basket operations: POST to /commerce/shopper-baskets/v1/organizations/{orgId}/baskets to create a basket. The POST response returns a basket object with an 'basketId' (a UUID). Store this basketId in a Bubble data type — name it 'SFCCBasket' with fields: basket_id (text), user (User), created_date (date). All subsequent basket operations (add item: POST to /baskets/{basketId}/items; remove item: DELETE to /baskets/{basketId}/items/{itemId}; get basket: GET /baskets/{basketId}) use this stored basket ID. Create a Backend Workflow 'SFCC_CreateBasket' that calls the Create Basket API action, then creates an SFCCBasket record with the returned basketId. On page load of your storefront, check if the current user has an SFCCBasket record. If not, trigger SFCC_CreateBasket. For the token refresh, confirm your Recurring Backend Workflow is active (check Settings → Backend Workflows in Bubble's editor). You can test it by manually editing an SFCCSession record to set token_expiry to 2 minutes from now — within 25 minutes, the Recurring Workflow should refresh it. In Bubble's Logs tab, look for the workflow execution records to confirm it ran. Finally, important context for any team considering this integration at scale: this architecture (proxy function + token management + basket state) represents a significant investment in infrastructure before a single shopper interacts with your store. If your team needs guidance designing this for a production deployment, RapidDev has hands-on experience with enterprise API integrations in Bubble — reach out at rapidevelopers.com/contact for a scoping conversation.

1// SCAPI Create Basket — POST to /baskets
2// Returns a basket object with basketId (use this for all subsequent cart operations)
3
4// POST /commerce/shopper-baskets/v1/organizations/{orgId}/baskets
5// Headers: Authorization: Bearer {accessToken} (from SFCCSession)
6// Body: {} (empty JSON object for guest basket)
7
8// Expected response (partial):
9{
10  "basketId": "bd2c4e0e9f9c4ce7826ab8c5e3af1a90",
11  "currency": "USD",
12  "productItems": [],
13  "creationDate": "2024-01-15T10:30:00.000Z",
14  "lastModified": "2024-01-15T10:30:00.000Z",
15  "orderTotal": 0.00
16}
17
18// Store basketId in SFCCBasket data type:
19// basket_id = bd2c4e0e9f9c4ce7826ab8c5e3af1a90
20// user = Current User
21// created_date = Current date/time
22
23// Add to cart — POST /baskets/{basketId}/items
24// Body:
25{
26  "productId": "<productId dynamic>",
27  "quantity": 1
28}