Skip to main content

​
Architecture Overview

Sticker’s embedded integration follows a simple but secure architecture that keeps your users authenticated across both platforms while providing a seamless procurement experience.

​
Integration Components

Backend Integration

Two API endpoints to call from your backend server

Frontend Embedding

iframe component to display Sticker in your UI

Organization Management

Automatic provisioning of orgs, users, and billing

Session Authentication

Secure, time-limited tokens for each user session

​
Two API Endpoints, That’s It

The entire integration requires just two API calls:

​
1. Organization Setup (One-Time)

Called when a customer enables procurement in your platform. 
POST /v1/organizations/setup
Creates:
  • Organization with Stripe customer for billing
  • User profile linked to Supabase Auth
  • Shipping locations for order delivery

​
2. Partner Handshake (Per-Session)

Called every time a user opens the supplies module. 
POST /v1/partner/handshake
Returns:
  • Session token (5 min, single-use)
  • Complete iframe embed URL

​
Integration Flow

​
One-Time Setup Flow

This happens once when a customer enables procurement:
1

Customer Enables Supplies

A customer clicks “Enable Supplies” in your platform
2

Gather Data

Collect organization name, user info, and shipping addresses from your system
3

Call Organization Setup

Send data to Sticker:
POST /v1/organizations/setup
{
  "internalOrgId": "your-org-id",
  "organizationName": "Customer Org",
  "internalUserId": "your-user-id",
  "user": {
    "firstName": "...",
    "lastName": "...",
    "email": "..."
  },
  "shippingLocations": [...]
}
4

Store Response

Optionally store the returned profile.id for reference
5

Enable UI

Show the supplies module in your navigation

​
Per-Session Authentication Flow

This happens every time a user opens supplies:
1

User Clicks Supplies

User navigates to the supplies section
2

Call Handshake

From your backend, call Sticker:
POST /v1/partner/handshake
{
  "internal_user_id": "your-user-id"
}
3

Get iframe URL

Response contains complete embed URL:
{
  "iframe_embed_url": "https://shop.usesticker.com/embedded/{partner}?session_key={token}"
}
4

Embed iframe

Display the iframe in your UI
5

User Shops

User browses, orders—all within your platform

​
Data Models

​
What You Send

// Organization Setup Request
{
  internalOrgId: string;        // YOUR org ID
  organizationName: string;     // Display name
  
  internalUserId: string;       // YOUR user ID  
  user: {
    firstName: string;
    lastName: string;
    email: string;
    phoneNumber?: string;
  };
  
  shippingLocations?: [{
    internalShippingLocationId: string;
    name: string;
    address: {
      line1: string;
      city: string;
      province: string;
      postalCode: string;
    };
    isDefault?: boolean;
  }];
}

​
What You Receive

// Organization Setup Response
{
  success: true,
  data: {
    organization: {
      id: string;             // Sticker org UUID
      stripeCustomerId: string;
    },
    profile: {
      id: string;             // Sticker profile UUID
      internal_user_id: string;  // Your ID echoed back
    },
    shippingLocations: [...],
    isNewOrganization: boolean;
  }
}

// Handshake Response
{
  success: true,
  session_key: string;
  iframe_embed_url: string;    // Use this directly!
  expires_at: string;
  profile: {
    id: string;
    first_name: string;
    last_name: string;
    email: string;
  }
}

​
Security Model

All API requests require your Partner API Key. Never expose it in client-side code.
// Organization Setup
Authorization: Bearer sk_live_xxx

// Handshake
X-API-Key: sk_live_xxx
  • 5 minute expiry - Must be used quickly
  • Single-use - Invalidated after first use
  • User-bound - Tied to specific profile
  • Partner-bound - Only works with your iframe URL
The iframe runs with restricted permissions:
sandbox="allow-same-origin allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-top-navigation-by-user-activation"

​
What’s Included Out of the Box

When you embed Sticker, your users get:
FeatureDescription
Product Catalog10,000+ products across categories
Smart SearchAlgolia-powered instant search
Shopping CartMulti-item cart with quantity management
Multiple LocationsSelect from org’s shipping addresses
Payment MethodsOrg-level saved payment methods
Coupon SupportPartner-funded discounts
Order HistoryView past orders and status
FavoritesSave frequently ordered items

​
Environments

EnvironmentAPI Base URLKeys
Productionhttps://api.usesticker.com/v1sk_live_*
Staging/Sandboxhttps://api.staging.usesticker.com/v1sk_test_*
Use sandbox for development and testing. Sandbox data is isolated from production.

​
Rate Limits

EndpointRate Limit
Organization Setup100/minute
Handshake300/minute
Implement exponential backoff for 429 responses.

​
Next Steps

Organization Setup

Provision organizations and users

User Handshake

Authenticate users for each session

iframe Embedding

Display Sticker in your application

Best Practices

Tips for a robust integration