7. Referrals (Optional)

Overview

BillStack includes a built-in per-project referral system that:

Generates unique 8-character referral codes for existing customers
Tracks when new customers sign up using a referral code
Automatically converts referrals from "pending" to "converted" when the referred customer creates a subscription (detected via webhooks)
Configurable credit amounts for both referrer and referee

Step 1: Configure the Referral Program

Enable referrals and set credit amounts for your project:

curl -X PUT \
  https://your-billstack.com/api/billstack/teams/{teamId}/projects/{projectId}/referrals/config \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "referrerCreditAmount": 1000,
    "refereeCreditAmount": 500,
    "currency": "usd"
  }'

Field	Type	Description
`enabled`	`boolean`	Whether referrals are active for this project
`referrerCreditAmount`	`number`	Amount (in cents) to credit the referrer
`refereeCreditAmount`	`number`	Amount (in cents) to credit the referee
`currency`	`string`	Currency code (default: `usd`)

Step 2: Generate Referral Codes

Create a referral code for an existing customer:

curl -X POST \
  https://your-billstack.com/api/billstack/teams/{teamId}/projects/{projectId}/referrals/codes \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "pc_xxx"
  }'

Response:

{
  "code": {
    "code": "A1B2C3D4",
    "customerId": "pc_xxx",
    "projectId": "proj_abc123",
    "isActive": true,
    "createdAt": "2026-03-30T12:00:00Z"
  }
}

Each customer gets one code per project. The code is 8 alphanumeric characters.

Step 3: Apply a Referral

When a new customer signs up with a referral code:

curl -X POST \
  https://your-billstack.com/api/billstack/teams/{teamId}/projects/{projectId}/referrals/apply \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "A1B2C3D4",
    "refereeCustomerId": "pc_new_customer"
  }'

Response:

{
  "referral": {
    "id": "ref_xxx",
    "code": "A1B2C3D4",
    "referrerCustomerId": "pc_xxx",
    "refereeCustomerId": "pc_new_customer",
    "status": "pending",
    "createdAt": "2026-03-30T12:00:00Z"
  }
}

The referral starts as pending. When the referred customer creates a subscription (detected by the checkout.session.completed or customer.subscription.created webhook), the referral is automatically converted.

Step 4: Integration Example

A typical referral flow in your SaaS app:

// 1. Show the referral code on the customer's dashboard
const { codes } = await billstack('/referrals/codes?limit=1');
const myCode = codes[0]?.code;

// 2. New user signs up with a referral code in the URL
// e.g., https://myapp.com/signup?ref=A1B2C3D4
const referralCode = searchParams.get('ref');

// 3. After creating the customer in BillStack, apply the referral
if (referralCode) {
  await billstack('/referrals/apply', {
    method: 'POST',
    body: JSON.stringify({
      code: referralCode,
      refereeCustomerId: newCustomer.id,
    }),
  });
}

// 4. When the customer subscribes (via checkout), the referral converts automatically

Managing Referral Codes

List all codes:

curl "https://your-billstack.com/.../referrals/codes?limit=50&offset=0&activeOnly=true" \
  -H "Authorization: Bearer bs_..."

View a code with its referral history:

curl https://your-billstack.com/.../referrals/codes/A1B2C3D4 \
  -H "Authorization: Bearer bs_..."

Deactivate a code:

curl -X DELETE https://your-billstack.com/.../referrals/codes/A1B2C3D4 \
  -H "Authorization: Bearer bs_..."

Tracking Referral Metrics

The analytics endpoint includes referral statistics:

curl https://your-billstack.com/.../analytics \
  -H "Authorization: Bearer bs_..."

The referralStats field returns:

{
  "referralStats": {
    "totalCodes": 50,
    "totalReferrals": 120,
    "converted": 95
  }
}

Migration Complete

Congratulations — you've migrated from direct Stripe to BillStack. Your SaaS apps now have:

Project-isolated billing with API key authentication
Automatic webhook routing
A self-hosted customer portal
Built-in analytics and referral tracking

See the API Reference for the complete endpoint documentation, or the TypeScript SDK for a ready-to-use client.

7. Referrals (Optional)

On this page