API reference

Authentication

Every request is a POST to https://tulpn.com/api/v1/events/… with your API key in the X-API-Key header. Create one on the API keys page of your business dashboard. Keep it on your server and never put it in browser code.

curl -X POST https://tulpn.com/api/v1/events/click \
  -H "X-API-Key: $TULPN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"promoter_code": "alex"}'

Click

POST /api/v1/events/click

Someone arrived through a promoter's link. Send it when your site sees the referral code, usually from a ?ref= parameter.

{
  "promoter_code": "alex"
}

Referral registered

POST /api/v1/events/referral-registered

A visitor who came through a promoter's link has signed up. external_customer_id is your own ID for the customer, and later events use it to find the right promoter.

{
  "promoter_code": "alex",
  "customer_email": "sam@example.com",
  "external_customer_id": "cus_123",
  "source": "link"
}

Purchase reported

POST /api/v1/events/purchase-reported

A referred customer paid. Send one for every invoice, including renewals, if you pay recurring commission.

{
  "external_customer_id": "cus_123",
  "external_subscription_id": "sub_456",
  "plan_interval": "monthly",
  "currency": "GBP",
  "amount_paid": "29.00",
  "invoice_external_id": "in_789"
}

• plan_interval is monthly, yearly or lifetime. It chooses which refund window applies.
• currency is a three-letter code such as GBP, EUR or USD. Amounts in another currency are converted into your payout currency at the European Central Bank rate for the day of the purchase. You can also convert them yourself and report them in your payout currency.
• amount_paid is the amount the customer actually paid, as a decimal. It can't be negative.

Subscription cancelled

POST /api/v1/events/subscription-cancelled

The customer cancelled. Commission still inside its refund window is voided.

{
  "external_subscription_id": "sub_456",
  "invoice_external_id": "in_789"
}

Refund reported

POST /api/v1/events/refund-reported

The customer got some or all of their money back.

{
  "external_subscription_id": "sub_456",
  "amount_refunded": "29.00",
  "invoice_external_id": "in_789"
}

Responses and errors

A successful call returns 200 with {"status": "ok"}.

Safe to retry

Events are idempotent per invoice_external_id, so if your webhook fires twice, the commission is still only counted once. Retry on network errors and 5xx responses as often as you like.

Unknown codes and customers

An event for a promoter code or customer that tulpn doesn't know about is accepted and quietly ignored. That way you can send every event without first checking whether the customer was referred.