Getting Started

Get Sync As A Service running in your app in 5 minutes.

---

Choose Your Integration Path

Path	Best For	Complexity	What You Get
Widget Only	Quick integration, user-facing features	⭐ Easy	Users connect retailers, you get notified
Widget + Backend API	Full data access, analytics, storage	⭐⭐⭐ Advanced	Full order data in your database

---

Path 1: Widget Only (Quickest)

The widget handles everything—authentication, retailer connection, and sync. You just embed it and react to events.

Step 1: Add the Widget

<div id="sync-widget"></div>

<script src="https://sync-api.stackline.com/sync-sdk/latest/sdk.umd.js"></script>
<script>
  SyncSDK.init({
    clientId: "bc_your_app_id",
    environment: "sandbox",
    container: document.getElementById("sync-widget"),

    // Called when sync completes
    onSync: (result) => {
      console.log(`Synced ${result.ordersFound} orders!`);
      showSuccessMessage(`Found ${result.ordersFound} orders`);
    },

    // Called for all widget events
    onEvent: (event, data) => {
      console.log("Widget event:", event, data);
    },
  });
</script>

Step 2: That's It!

The widget handles:

• ✅ Phone authentication (OTP)

• ✅ Retailer selection and login

• ✅ MFA challenges

• ✅ Sync progress

• ✅ Error handling and retry

You receive:

• onSync callback with { ordersFound } when sync completes

• onEvent callbacks for tracking user progress

What you DON'T get:

• ❌ Direct access to order data (products, prices, dates)

• ❌ API access from your backend

When to use: You want to show users their connected retailers and sync status, but don't need to process order data yourself.

---

Path 2: Widget + Backend API (Full Integration)

You need this path if you want to:

• Store order data in your own database

• Process orders for rewards/analytics

• Build features based on purchase history

How It Works

+------------------+     +------------------+     +------------------+
|   Your Frontend  |     |   Your Backend   |     | Sync As A Service|
+------------------+     +------------------+     +------------------+
        |                        |                        |
        |  1. Embed widget       |                        |
        |----------------------->|                        |
        |                        |                        |
        |  2. User authenticates via widget               |
        |------------------------------------------------>|
        |                        |                        |
        |  3. Widget: onSync({ ordersFound })             |
        |<------------------------------------------------|
        |                        |                        |
        |  4. "Sync complete!"   |                        |
        |  Notify backend        |                        |
        |----------------------->|                        |
        |                        |                        |
        |                        |  5. Backend fetches    |
        |                        |     order data         |
        |                        |----------------------->|
        |                        |                        |
        |                        |  6. Returns orders     |
        |                        |<-----------------------|
        |                        |                        |
        |  7. Display orders     |                        |
        |<-----------------------|                        |
+------------------+     +------------------+     +------------------+

Step 1: Embed the Widget (Frontend)

Same as Path 1—the widget handles user experience:

<div id="sync-widget"></div>

<script src="https://sync-api.stackline.com/sync-sdk/latest/sdk.umd.js"></script>
<script>
  SyncSDK.init({
    clientId: "bc_your_app_id",
    environment: "sandbox",
    container: document.getElementById("sync-widget"),

    onSync: async (result) => {
      console.log(`Synced ${result.ordersFound} orders`);

      // Notify your backend that sync is complete
      await fetch("/api/sync-complete", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          userId: getCurrentUserId(), // Your user ID
          ordersFound: result.ordersFound,
        }),
      });

      // Refresh your UI with new data
      await refreshOrdersUI();
    },
  });
</script>

Step 2: Implement OAuth2 (Backend)

To fetch order data from your backend, you need an access token. This requires implementing OAuth2:

2a. Redirect user to authorize:

GET https://sync-api.stackline.com/oauth2/authorize
  ?client_id=bc_your_app_id
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=orders:read
  &state={random_state}

2b. Exchange code for token:

// Your /callback endpoint
app.get("/callback", async (req, res) => {
  const { code, state } = req.query;

  // Verify state matches what you sent
  if (state !== req.session.oauth_state) {
    return res.status(400).send("Invalid state");
  }

  // Exchange code for tokens
  const tokenResponse = await fetch(
    "https://sync-api.stackline.com/oauth2/token",
    {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({
        grant_type: "authorization_code",
        client_id: "bc_your_app_id",
        client_secret: process.env.BC_CLIENT_SECRET,
        code: code,
        redirect_uri: "https://yourapp.com/callback",
      }),
    }
  );

  const tokens = await tokenResponse.json();

  // Store tokens securely (encrypted, server-side only)
  await saveTokensForUser(req.session.userId, tokens);

  res.redirect("/accounts");
});

2c. Store tokens securely:

// Store encrypted in your database
async function saveTokensForUser(userId, tokens) {
  await db.users.update(userId, {
    bc_access_token: encrypt(tokens.access_token),
    bc_refresh_token: encrypt(tokens.refresh_token),
    bc_token_expires_at: Date.now() + tokens.expires_in * 1000,
  });
}

Step 3: Fetch Order Data (Backend)

Now you can fetch orders from your backend:

// Your /api/orders endpoint
app.get("/api/orders", async (req, res) => {
  const userId = req.session.userId;

  // Get stored token
  const user = await db.users.findById(userId);
  const accessToken = decrypt(user.bc_access_token);

  // Refresh token if expired
  if (Date.now() > user.bc_token_expires_at) {
    accessToken = await refreshAccessToken(userId);
  }

  // Fetch orders from Sync As A Service
  const response = await fetch("https://sync-api.stackline.com/sync/orders", {
    headers: { Authorization: `Bearer ${accessToken}` },
  });

  const orders = await response.json();

  // Optional: Store in your database for faster access
  await storeOrdersInYourDB(userId, orders);

  res.json(orders);
});

Step 4: Display in Your App (Frontend)

// Fetch orders from YOUR backend (not Sync As A Service directly)
async function refreshOrdersUI() {
  const response = await fetch("/api/orders", {
    headers: { Authorization: `Bearer ${yourSessionToken}` },
  });

  const orders = await response.json();
  renderOrdersTable(orders);
}

---

Why Backend API vs Frontend?

Why can't the frontend call Sync As A Service directly?

1. Security - Access tokens contain user data; exposing them to the browser is risky

2. CORS - API doesn't allow direct browser calls (prevents token theft)

3. Your data - You likely want orders in your database, not just displayed

The pattern:

Browser → Your Backend → Sync As A Service API
           (token stored     (returns order data)
            server-side)

---

Alternative: Webhooks (Coming Soon)

Instead of polling the API, we can push order data to your server:

// Your webhook endpoint
app.post("/webhooks/sync-complete", async (req, res) => {
  const { userId, orders, syncBatchId } = req.body;

  // Verify webhook signature
  if (!verifySignature(req)) {
    return res.status(401).send("Invalid signature");
  }

  // Store orders in your database
  await storeOrders(userId, orders);

  res.status(200).send("OK");
});

Contact us to enable webhooks for your integration.

---

Test Credentials

For sandbox testing:

• Phone: [phone]

• OTP Code: 424242

• Demo Client: bc_demo_sync_beta

---

Go to Production

1. Change environment: "sandbox" → environment: "production"

2. Update API URLs from sync-api-beta.stackline.com → sync-api.stackline.com

3. Use your production Client ID and Secret

---

What's Next?

• Widget Reference - All widget states and customization

• API Reference - REST API endpoints

• Data Reference - Order data structure