Build with Sorae

Sorae supports two implementation paths: widget-first for fast deployment with prebuilt UI surfaces, and API-first for teams building custom experiences. Both paths use the same underlying campaign engine, attribution model, and reward logic.

Choosing Your Path

Widget-first is the right choice when you want to launch quickly without building UI from scratch. Sorae's prebuilt widgets handle advocate start, friend claim, and affiliate portal views. Drop in the SDK, configure your campaign, and the widgets render with live campaign state.

API-first (headless) is the right choice when your storefront has existing UI patterns you need to maintain, or when you're integrating Sorae into a product with its own component system. Every widget behavior is available as a headless SDK method backed by a public API endpoint.

Both paths use the same Sorae.init() configuration and produce the same attribution data.

JS SDK Quickstart

import { Sorae } from "@sorae/js";

const client = Sorae.init({
  apiBaseUrl: "https://api.sorae.io",
  accountId: "acct_123",
  campaignSlug: "spring-referral",
  shopDomain: "store.myshopify.com" // Shopify only
});

For non-Shopify workspaces, omit shopDomain and pass your workspace API key in the request headers or use the apiKey config option.

Prebuilt Widgets

Widgets render the complete UI experience for a given advocate or affiliate view. Pass a mount target and the widget handles data fetching, state management, and rendering.

// Advocate start view, collect identity and issue share link
client.renderAdvocateWidget({
  mountTo: "#advocate-portal",
  campaignSlug: "spring-referral",
});

// Friend claim view, shown to referred friends on landing
client.renderFriendWidget({
  mountTo: "#friend-claim",
});

// Affiliate portal, commission and payout history view
client.renderAffiliatePortal({
  mountTo: "#affiliate-portal",
});

Widgets are styled with sensible defaults and accept class name overrides for brand alignment. For Shopify merchants, widgets are also deployable via theme app extensions without any SDK initialization code.

Headless API Methods

Use headless methods when you want to drive behavior through your own UI components.

// Start an advocate, collect identity, return share link
const { shareLink, advocateId } = await client.advocateStart({
  email: "[email protected]",
  name: "Jane Smith",
});

// Get current advocate status for in-page rendering
const status = await client.getAdvocateStatus({ email: "[email protected]" });
// { inviteCount: 3, conversionCount: 1, pendingRewards: 1 }

// Resolve attribution code from current URL/session
const attribution = await client.resolveAttribution();
// { type: "referral" | "affiliate", code: "abc123", advocateId: "..." }

// Apply as an affiliate
const application = await client.affiliateApply({
  email: "[email protected]",
  name: "Alex Creator",
  platformUrl: "https://instagram.com/alexcreator",
});

All methods return typed responses and throw structured errors for network failures, policy violations, and invalid campaign states. Full TypeScript definitions ship with the SDK package.

Attribution Integration

For checkout attribution on Shopify, the tracking embed handles context capture automatically once enabled via App Embeds in the Theme Editor. For non-Shopify or custom implementations, call resolveAttribution() on checkout page initialization and pass the attribution code to your order metadata.

// On checkout page load
const attribution = await client.resolveAttribution();

if (attribution) {
  // Pass to your order creation API
  myCheckout.setOrderMetadata({
    sorae_attribution_code: attribution.code,
    sorae_attribution_type: attribution.type,
  });
}

Sorae's API reads the attribution metadata on your order webhook payload to match conversions to the correct advocate or affiliate record.

Public API Overview

All SDK methods wrap public REST API endpoints. You can call these directly from your backend without the browser SDK for server-side integration patterns.

Authentication: Pass your API key in the Authorization: Bearer <key> header. Generate API keys from the workspace settings page.

Base URL: https://api.sorae.io

Key endpoint groups:

• /v1/advocates, Advocate start, status, invite tracking
• /v1/affiliates, Application intake, approval, portal data
• /v1/attribution, Code resolution, session context binding
• /v1/analytics, Campaign metrics, funnel data, leaderboards
• /v1/rewards, Reward status, issuance history

All endpoints use JSON request/response bodies and return structured error objects with code, message, and details fields for consistent error handling.

Webhooks and HMAC Verification

Sorae emits webhook events for key lifecycle moments. Configure your webhook endpoint in workspace settings, then verify incoming requests using HMAC signature verification.

import crypto from "crypto";

function verifyWebhookSignature(payload, signature, secret) {
  const computed = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(signature)
  );
}

Available webhook events:

| Event | Description | |-------|-------------| | advocate.started | New advocate joined the program | | invite.sent | Advocate sent an invite | | conversion.finalized | Referred order converted and passed eligibility | | reward.issued | Reward discount code issued to advocate | | affiliate.applied | New affiliate application received | | affiliate.approved | Affiliate application approved | | commission.accrued | Commission row created for a conversion |

Implementation Sequence

For Shopify merchants:

1. Install Sorae from the Shopify App Store
2. Complete the setup checklist: publish pages, place widgets, enable tracking embed
3. Validate attribution events with a test referral before launching
4. Connect Klaviyo if you use lifecycle email marketing

For non-Shopify platforms:

1. Create a workspace account at workspace.sorae.io
2. Generate an API key from workspace settings
3. Configure your first campaign with reward and eligibility settings
4. Choose SDK widget-first or headless API path
5. Implement attribution context capture on your checkout flow
6. Set up webhook endpoint and HMAC verification
7. Connect Klaviyo or build your own event routing from webhook events

Testing Your Integration

Before going live, validate three end-to-end flows:

1. Referral flow: Create a test advocate → get share link → visit share link in incognito → complete a test order → verify conversion and reward events appear in analytics.

2. Affiliate flow: Submit a test application → approve from admin → distribute affiliate link → complete a test order → verify commission row is created.

3. Attribution persistence: For Shopify, complete the referral flow through guest checkout specifically, this is the most common failure point in storefront integrations.

Check the analytics dashboard after each test flow. If click events appear but conversions don't, the order attribute write step is missing. If conversions appear but rewards don't issue, check eligibility rules, most commonly the new-customer check or minimum subtotal.

Help for Developers

For technical questions on SDK usage, API contracts, or webhook integration patterns, contact [email protected] or book a technical walkthrough with the implementation team.