Referrals

All referral endpoints are scoped to a project:

/api/billstack/teams/{teamId}/projects/{projectId}/referrals/...

Configuration

Get Referral Config

GET /referrals/config

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

Response:

{
  "config": {
    "enabled": true,
    "referrerCreditAmount": 1000,
    "refereeCreditAmount": 500,
    "currency": "usd",
    "projectId": "proj_abc123"
  }
}

Auth: Read access (session or API key with referrals:read).

Update Referral Config

PUT /referrals/config

Field	Type	Required	Description
`enabled`	`boolean`	Yes	Enable or disable referrals
`referrerCreditAmount`	`number`	Yes	Credit for the referrer (in cents)
`refereeCreditAmount`	`number`	Yes	Credit for the referee (in cents)
`currency`	`string`	No	Currency code (default: `usd`)

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

Auth: Write access (session or API key with referrals:write).

Referral Codes

List Codes

GET /referrals/codes?limit=50&offset=0&activeOnly=true

Parameter	Type	Default	Description
`limit`	`number`	`50`	Max items to return
`offset`	`number`	`0`	Items to skip
`activeOnly`	`boolean`	`true`	Only return active codes

curl "https://your-billstack.com/.../referrals/codes?limit=25" \
  -H "Authorization: Bearer bs_..."

Response:

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

Auth: Read access.

Create Code

POST /referrals/codes

Field	Type	Required	Description
`customerId`	`string`	Yes	BillStack customer ID who will be the referrer

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

Response (201):

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

Generates a unique 8-character alphanumeric code. Each customer can have one active code per project.

Auth: Write access.

Get Code

GET /referrals/codes/{code}

Returns the code details along with its referral history.

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

Response:

{
  "code": {
    "code": "A1B2C3D4",
    "customerId": "pc_a1b2c3d4",
    "isActive": true,
    "createdAt": "2026-03-30T12:00:00Z"
  },
  "referrals": [
    {
      "id": "ref_xxx",
      "refereeCustomerId": "pc_new1",
      "status": "converted",
      "createdAt": "2026-03-15T10:00:00Z",
      "convertedAt": "2026-03-15T10:30:00Z"
    },
    {
      "id": "ref_yyy",
      "refereeCustomerId": "pc_new2",
      "status": "pending",
      "createdAt": "2026-03-28T14:00:00Z",
      "convertedAt": null
    }
  ]
}

Auth: Read access.

Deactivate Code

DELETE /referrals/codes/{code}

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

Response:

{
  "code": {
    "code": "A1B2C3D4",
    "isActive": false
  }
}

Deactivated codes can no longer be used for new referrals. Existing pending referrals are not affected.

Auth: Write access.

Apply Referral

POST /referrals/apply

Records that a new customer signed up using a referral code.

Field	Type	Required	Description
`code`	`string`	Yes	The 8-character referral code
`refereeCustomerId`	`string`	Yes	BillStack customer ID of the new customer

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

Response (201):

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

Auth: Read access (session or API key — intentionally low barrier so signup flows can apply codes).

Referral Lifecycle

Code created — referrer gets a shareable code
Referral applied — new customer signs up with the code, status: pending
Referral converted — the referee creates a subscription (detected via checkout.session.completed or customer.subscription.created webhook), status: converted

Conversion is automatic — no manual API call needed after the referral is applied.

Referrals

On this page