Partner Program

Let users apply to become partners who earn commissions by referring new customers. Includes application flow, approval workflow, and webhook notifications.

How It Works

A user submits a partner application via your site (no account required)
The application appears in your StackBE dashboard for review
You approve or reject from the dashboard (or via API)
On approval, a customer account and partner record are created automatically
The partner gets a referral code and starts earning commissions

Setup

Go to app.stackbe.io → Your App → Settings
Enable the Affiliate Program
Navigate to the Affiliates tab in the sidebar
Partner applications will appear under the Applications tab

Accepting Applications

Anyone can apply to become a partner using your app's API key. No account is needed.

Via SDK

typescript

import { StackBE } from '@stackbe/sdk';

const stackbe = new StackBE({
  apiKey: process.env.STACKBE_API_KEY!,
  appId: process.env.STACKBE_APP_ID!,
});

const result = await stackbe.affiliates.apply({
  email: 'partner@example.com',
  name: 'Jane Smith',
  company: 'Acme Inc',        // optional
  website: 'https://acme.com', // optional
  reason: 'I have a large audience in the SaaS space', // optional
});

console.log(result.status); // 'pending'

Via REST API

bash

curl -X POST https://api.stackbe.io/v1/affiliate/apply \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "partner@example.com",
    "name": "Jane Smith",
    "company": "Acme Inc",
    "website": "https://acme.com",
    "reason": "I have a large audience in the SaaS space"
  }'

Returns { id, status: 'pending', message: '...' }. Duplicate applications from the same email are rejected with a 409.

Checking Application Status

Check if a user has applied and what their status is — without side effects.

typescript

const status = await stackbe.affiliates.getApplicationStatus('partner@example.com');

if (!status.applied) {
  // Show "Apply to become a partner" button
} else if (status.status === 'pending') {
  // Show "Your application is under review"
} else if (status.status === 'approved') {
  // Show partner dashboard
} else if (status.status === 'rejected') {
  // Show rejection reason
  console.log(status.rejectionReason);
}

Via REST API

bash

curl https://api.stackbe.io/v1/affiliate/apply/status?email=partner@example.com \
  -H "x-api-key: YOUR_API_KEY"

Server-Side Partner Check

Check if a customer is an approved partner from your backend using their customer ID. No session token needed — just your API key.

typescript

// Server-side: check if a customer is a partner
const info = await stackbe.affiliates.get('cust_123');

if (info.enrolled && info.status === 'active') {
  // Customer is an active partner
  console.log(`Partner code: ${info.code}`);
  console.log(`Total earned: $${info.totalEarned}`);
}

Via REST API

bash

curl https://api.stackbe.io/v1/affiliate/by-customer/cust_123 \
  -H "x-api-key: YOUR_API_KEY"

Returns { enrolled: true, id, code, type, status, totalEarned, ... } or { enrolled: false }.

Reviewing Applications

Review applications from the Affiliates → Applications tab in the StackBE dashboard. You can also approve or reject via the API:

Approve

bash

curl -X POST https://api.stackbe.io/v1/apps/APP_ID/affiliates/applications/APPLICATION_ID/review \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "approve",
    "code": "JANE20"
  }'

The code field is optional — a referral code is auto-generated if omitted. On approval, a customer account is created automatically if the applicant doesn't have one yet.

Reject

bash

curl -X POST https://api.stackbe.io/v1/apps/APP_ID/affiliates/applications/APPLICATION_ID/review \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "reject",
    "rejectionReason": "Not a good fit at this time"
  }'

Webhooks

Subscribe to these events to react to application decisions in real time:

Partner Application Events

partner_application_approved — Application was approved. Includes application (id, email, name) and affiliate (id, code, customer_id).
partner_application_rejected — Application was rejected. Includes application (id, email, name, reason).

Example Payload

json

{
  "event": "partner_application_approved",
  "data": {
    "application": {
      "id": "cmxyz...",
      "email": "partner@example.com",
      "name": "Jane Smith"
    },
    "affiliate": {
      "id": "cmxyz...",
      "code": "JANE20",
      "customer_id": "cust_123"
    }
  }
}

Use these events to automatically notify users, update your local database, or trigger onboarding flows.

Partner Earnings

Configure these in your affiliate program settings:

Setting	Default	Description
`defaultCommissionRate`	20%	Percentage of referred subscription revenue
`holdingPeriodDays`	30	Days before commissions are approved
`minPayoutAmount`	$50	Minimum balance before payout
`cookieDurationDays`	30	How long referral attribution lasts

Partner Tools (After Approval)

Once approved, partners can access their stats and tools via the SDK (using their customer session token):

typescript

// Get partner dashboard
const dashboard = await stackbe.affiliates.getDashboard();
console.log(`Total earned: $${dashboard.affiliate.totalEarned}`);
console.log(`Pending balance: $${dashboard.affiliate.pendingBalance}`);

// Get hosted partner portal link (branded, valid 24h)
const { url } = await stackbe.affiliates.getPortalLink();
// Redirect partner to the portal URL

// Track a referral click
await stackbe.affiliates.trackReferral('JANE20', 'https://yoursite.com?ref=JANE20');

// Register a deal
await stackbe.affiliates.registerDeal({
  leadEmail: 'prospect@company.com',
  leadName: 'John Smith',
  notes: 'Met at conference',
});

API Reference

Endpoint	Auth	Description
`POST /v1/affiliate/apply`	API key	Submit a partner application
`GET /v1/affiliate/apply/status`	API key	Check application status by email
`GET /v1/affiliate/by-customer/:id`	API key	Server-side partner lookup
`GET /v1/affiliate`	Session	Get current customer's partner info
`GET /v1/affiliate/dashboard`	Session	Full partner dashboard
`GET /v1/affiliate/portal-link`	Session	Hosted partner portal link
`POST /v1/affiliate/track`	API key	Track a referral click
`GET /v1/apps/:appId/affiliates/applications`	JWT	List applications (admin)
`POST .../applications/:id/review`	JWT	Approve or reject (admin)