DocumentationAPI ReferenceContact UsGet Started
Introduction

Affiliates

List affiliates GETGet affiliate GETCreate affiliate POSTUpdate affiliate PUT

Campaigns

List campaigns GETGet campaign GETCreate campaign POSTUpdate campaign PUT

Referrals

List referrals GETCreate referral POST

Commissions

List commissions GETGet commission GETCreate commission POST

Payouts

List payouts GETGet payout GET
Referrals

Create referral

Creates a new referral for an affiliate in your organization.

Referrals are automatically created and tracked when you follow the affiliate links setup steps or affiliate promo codes setup steps. Only use this endpoint to manually track referred users from your backend. To manually track referred users from your app's frontend, use the window.promotekit.refer(email) function instead.

POST
/referrals

Authorization

Authorization
Required
Bearer <token>

In: header

Request Body

application/jsonRequired

affiliate_id
Required
string

Format: "uuid"

email
Required
string

Format: "email"

stripe_customer_idstring

subscription_statusstring

Value in: "active" | "signed_up" | "trialing" | "canceled" | "past_due"

Previous

List referrals GET

Next

List commissions GET

/referrals

The Authorization access token

API key authentication. Use your API key as the bearer token.

UUID of the affiliate this referral belongs to

Email address of the referred customer

Stripe customer ID of the referred customer

Subscription status of the referred customer

Successful response

curl -X POST "https://www.promotekit.com/api/v1/referrals" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "affiliate_id": "3b7d610b-bb33-4bfb-8025-7abb425f8603",
    "email": "user@example.com",
    "stripe_customer_id": "string",
    "subscription_status": "active"
  }'
{
  "success": true,
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "email": "user@example.com",
    "subscription_status": "active",
    "signup_date": "2019-08-24T14:15:22Z",
    "stripe_customer_id": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "affiliate": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "email": "user@example.com",
      "first_name": "string",
      "last_name": "string",
      "payout_email": "user@example.com",
      "links": [
        {
          "url": "string",
          "code": "string"
        }
      ],
      "promo_codes": [
        {
          "code": "string",
          "external_id": "string"
        }
      ],
      "clicks": 0,
      "approved": true,
      "banned": true,
      "details": "string",
      "new_paid_referral_notifications": true,
      "created_at": "2019-08-24T14:15:22Z",
      "campaign": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "created_at": "2019-08-24T14:15:22Z",
        "website_url": "string",
        "commission_type": "percentage",
        "commission_amount": 0,
        "is_default": true,
        "limit_type": "string",
        "limit_amount": 0,
        "code_mode": "link",
        "reference_coupon": "string",
        "custom_commission_type": "string",
        "welcome_message": "string",
        "approval_needed": true,
        "collect_details": true,
        "details_text": "string",
        "hide_emails": true,
        "dashboard_text": "string",
        "cookie_duration": 0,
        "first_payment_commission": {
          "enabled": true,
          "type": "string",
          "amount": 0
        }
      }
    }
  }
}