Darkbloom has a referral program that lets you generate a personal referral code and share it with others. When someone uses your code during their first deposit, both parties may receive a benefit. You can manage and track your referrals entirely through the API. This page shows the three steps: registering a code, applying a code, and checking your stats.
Step 1 — Register a referral code
To create a referral code for your account, call POST /v1/referral/register. This requires authentication.
curl -X POST https://api.darkbloom.dev/v1/referral/register \
-H "Authorization: Bearer $DARKBLOOM_API_KEY" \
-H "Content-Type: application/json"
Step 2 — Apply a referral code
When someone else is making a deposit and has a referral code, they can apply it at checkout time. Pass the code in the referral_code field when creating a Stripe checkout session:
curl -X POST https://api.darkbloom.dev/v1/billing/stripe/create-session \
-H "Authorization: Bearer $DARKBLOOM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount_usd": "10.00",
"referral_code": "YOURCODE"
}'
POST /v1/referral/apply:
curl -X POST https://api.darkbloom.dev/v1/referral/apply \
-H "Authorization: Bearer $DARKBLOOM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"referral_code": "YOURCODE"
}'
Referral codes are validated before the checkout session is created. If the code is invalid, the request will return a 400 error and no checkout session will be started.
Step 3 — Check referral stats
To see how many people have used your code and any associated activity, call GET /v1/referral/stats:
curl https://api.darkbloom.dev/v1/referral/stats \
-H "Authorization: Bearer $DARKBLOOM_API_KEY"
Endpoint summary
| Method | Endpoint | Description |
|---|
POST | /v1/referral/register | Create a referral code for your account |
POST | /v1/referral/apply | Apply a referral code to your account |
GET | /v1/referral/stats | View referral activity and stats |