# PromoteKit Documentation (Full)

This file contains the complete PromoteKit documentation for AI/LLM consumption.
It includes both product documentation and API reference.

---
# Product Documentation

---



---

# Quick Start
URL: /docs
Description: Getting Started with PromoteKit

# Introduction

PromoteKit is a platform for running affiliate programs on top of Stripe. We've focused on creating **the most seamless possible integration with Stripe** - so you can integrate quickly and get back to focusing on your business.

  - [Affiliate Promo Codes](/docs/affiliate-promo-codes): Assign unique promo codes to affiliates and track referrals through Stripe
    Checkout
  - [Affiliate Links](/docs/affiliate-links): Give affiliates unique tracking links to refer customers to your site
  - [Integrations](/docs/integrations): Connect with Memberstack, Outseta, MemberSpace, and more
  - [Payouts](/docs/payouts): Process affiliate payments via PayPal, Wise, or manual methods
  - [API Reference](/docs/api-reference): Build custom integrations with the PromoteKit REST API
  - [Webhooks](/docs/webhooks): Receive real-time event notifications for your affiliate program

> **Note:** Need help? Contact us at hello@promotekit.com

---

# Affiliate Links Setup
URL: /docs/affiliate-links
Description: Track affiliate referrals using unique tracking links

# Overview

PromoteKit provides each affiliate with a unique tracking link. When a visitor clicks an affiliate's link and makes a purchase, the referral is automatically tracked.

## How It Works

1. Affiliate shares their unique link (e.g., `yoursite.com?via=abc123`)
2. Visitor clicks the link and lands on your site
3. PromoteKit script stores the referral ID in a cookie
4. When the visitor purchases, the referral ID is sent to Stripe
5. PromoteKit attributes the sale to the affiliate

## Setup Methods

  - [Stripe API](/docs/affiliate-links/stripe-api): Pass referral IDs through the Stripe API for custom checkout flows
  - [Stripe Payment Links](/docs/affiliate-links/stripe-payment-links): Use with Stripe Payment Links for a no-code solution

> **Note:** Affiliate link tracking requires adding the PromoteKit script to your website.
  [Promo code tracking](/docs/affiliate-promo-codes) does not require any
  script.

---

# Stripe API Integration
URL: /docs/affiliate-links/stripe-api
Description: Pass referral IDs through the Stripe API for affiliate tracking

# Overview

For custom checkout flows, you can pass the referral ID directly through the Stripe API.

<iframe
  width="100%"
  style={{ aspectRatio: '16/9' }}
  src="https://www.youtube.com/embed/RCOGOdtGXro"
  title="Stripe API integration for affiliate tracking"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
/>

## Implementation Steps

### 1. Add the PromoteKit Script

Add the PromoteKit script to your website. It should be on both your landing page (where referrals arrive) and your checkout page.

The script works across subdomains, so you can use it on both `yoursite.com` and `app.yoursite.com`.

### 2. Retrieve the Referral ID

After the script loads, you can access the referral ID:

**JavaScript/TypeScript:** Use `window.promotekit_referral`

**PHP:** Use `$_COOKIE['promotekit_referral']`

### 3. Pass to Stripe

Include the referral ID in the metadata when creating a checkout session or subscription:

```javascript
const session = await stripe.checkout.sessions.create({
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  metadata: {
    promotekit_referral: req.body.referral,
  },
  line_items: [{ price: 'price_1OBQlV2eZvKYlo2CDL02DbMx', quantity: 1 }],
  mode: 'subscription',
});
```

## Manual Signup Tracking

For tracking users who sign up before they pay, use the `refer` function:

`window.promotekit.refer(email, stripe_customer_id)`

| Parameter            | Required | Description                       |
| -------------------- | -------- | --------------------------------- |
| `email`              | Yes      | Customer's email address          |
| `stripe_customer_id` | No       | Stripe customer ID (if available) |

This allows you to attribute the referral before payment occurs.

---

# Stripe Payment Links
URL: /docs/affiliate-links/stripe-payment-links
Description: Use PromoteKit with Stripe Payment Links for no-code affiliate tracking

# Stripe Payment Links Integration

If you use [Stripe Payment Links](https://stripe.com/payments/payment-links) or [Stripe Pricing Tables](https://docs.stripe.com/payments/checkout/pricing-table), PromoteKit provides a simple script-based solution that requires no custom API integration.

<iframe
  width="100%"
  style={{ aspectRatio: '16/9' }}
  src="https://www.youtube.com/embed/-1aeNHmzXKs"
  title="Stripe Payment Links affiliate tracking setup"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
/>

## Setup Steps

  1. ### Get the Script
   
       1. Go to your PromoteKit dashboard
       2. Navigate to **Setup → Step 4 (PromoteKit Integration)**
       3. Click **OPTION 2: Stripe Payment Links**
       4. Copy the provided script
  2. ### Add to Your Website
   
       Paste the script into your website's custom code section. You can add it to either the `<head>` or `<body>` section.
  3. ### Publish and Confirm
   
       1. Publish your website
       2. Return to PromoteKit and click **Ok, I've completed this**

## Adding Custom Code on Different Platforms

  - [Webflow](https://university.webflow.com/lesson/custom-code-in-the-head-and-body-tags): Adding custom code to head and body tags
  - [Framer](https://www.framer.com/help/articles/how-to-add-custom-code/): Custom code implementation in Framer
  - [WordPress](https://www.wpbeginner.com/plugins/how-to-easily-add-custom-code-in-wordpress-without-breaking-your-site/): Adding custom code safely in WordPress

> **Note:** This integration works with both [Stripe Payment Links](https://stripe.com/payments/payment-links) and [Stripe Pricing Tables](https://docs.stripe.com/payments/checkout/pricing-table).

---

# Affiliate Promo Codes Setup
URL: /docs/affiliate-promo-codes
Description: Track affiliate referrals using unique promo codes in Stripe

# Overview

PromoteKit assigns unique promo codes to each affiliate. When a customer uses an affiliate's promo code at checkout, the referral is automatically tracked and the affiliate earns their commission.

## How It Works

1. You create a coupon in Stripe with a discount (e.g., 10% off)
2. PromoteKit automatically generates unique promo codes for each affiliate based on that coupon
3. Affiliates share their promo codes with potential customers
4. When customers use the code at checkout, PromoteKit tracks the referral

## Setup Methods

  - [Stripe Checkout](/docs/affiliate-promo-codes/stripe-checkout): Enable promo codes on Stripe Checkout with a single parameter
  - [Stripe API](/docs/affiliate-promo-codes/stripe-api): Use the Stripe API directly for custom checkout flows
  - [Default Coupon Code](/docs/affiliate-promo-codes/default-coupon-code): Configure your default coupon for affiliate promo codes

> **Note:** No website script is required for promo code tracking. It works entirely through Stripe.

---

# Setting a Default Coupon Code
URL: /docs/affiliate-promo-codes/default-coupon-code
Description: Configure your default coupon for generating affiliate promo codes

# Setup

Before PromoteKit can generate promo codes for your affiliates, you need to create a coupon in Stripe and set it as your default.

<iframe
  width="100%"
  style={{ aspectRatio: '16/9' }}
  src="https://www.youtube.com/embed/NGNnHjOfjyw"
  title="Setting up coupon codes in PromoteKit"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
/>

## Understanding Coupons vs Promo Codes

- **Coupon**: Holds the discount details (e.g., 10% off, $5 off)
- **Promo Code**: A unique code linked to a coupon that customers enter at checkout

PromoteKit uses one coupon to generate unlimited unique promo codes for each affiliate automatically.

## Setup Steps

  1. ### Create a Coupon in Stripe
   
       Go to your [Stripe Dashboard](https://dashboard.stripe.com/coupons) and create a new coupon with your desired discount.
  2. ### Configure in PromoteKit
   
       1. Go to the **Setup** tab in your PromoteKit dashboard
       2. Navigate to **Step 4 (PromoteKit Integration)**
       3. Select **OPTION 3: Coupon Codes**
       4. Choose your default coupon from the dropdown
       5. Click **Ok, I've completed this**
  3. ### Test the Setup
   
       Sign up as a test affiliate through your affiliate portal. Upon successful registration, you should receive a unique Stripe promo code based on your default coupon.

> **Note:** Make sure to test in Stripe **live mode**. Promo codes created in test mode
  won't work in production.

---

# Stripe API Integration
URL: /docs/affiliate-promo-codes/stripe-api
Description: Use the Stripe API directly for promo code tracking

# Overview

For custom checkout flows or mobile apps, you can use the Stripe API directly to apply affiliate promo codes.

This approach is particularly useful for mobile apps where traditional affiliate link tracking may be restricted by app stores.

## Implementation Steps

### 1. Retrieve the Promo Code ID

When a user enters a promo code on your checkout screen, call the [Stripe Promotion Codes API](https://stripe.com/docs/api/promotion_codes/list) to get the promo code ID. Use `stripe.promotionCodes.list` with the code parameter set to the entered code.

### 2. Apply to Subscription

When [creating a subscription](https://docs.stripe.com/api/subscriptions/create), include the `promotion_code` parameter with the promo code ID you retrieved:

```javascript
const subscription = await stripe.subscriptions.create({
  customer: 'cus_Na6dX7aXxi11N4',
  items: [
    {
      price: 'price_1MowQULkdIwHu7ixraBm864M',
    },
  ],
  promotion_code: 'promo_1MiM6KLkdIwHu7ixrIaX4wgn',
});
```

## Alternative: Update Existing Subscription

You can also apply promo codes to existing subscriptions using the [subscription update API](https://docs.stripe.com/api/subscriptions/update) with the `promotion_code` parameter.

Referral attribution works identically whether you apply the code at creation or update time.

---

# Stripe Checkout Integration
URL: /docs/affiliate-promo-codes/stripe-checkout
Description: Enable promo codes in Stripe Checkout for affiliate tracking

# Overview

Promo code tracking with Stripe Checkout requires almost no setup. No website script is required.

## Implementation Methods

### Via Stripe API

When creating a checkout session via the Stripe API, include `allow_promotion_codes: true` in your checkout session creation call:

```javascript
const session = await stripe.checkout.sessions.create({
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  allow_promotion_codes: true,
  line_items: [
    { price: 'price_1OBQlV2eZvKYlo2CDL02DbMx', quantity: 1 },
  ],
  mode: 'subscription',
});
```

### Via Stripe Payment Links

For Stripe Payment Links, enable promo codes through the Stripe Dashboard:

1. Go to your Stripe Dashboard and find your Payment Link
2. Click **Edit** on the Payment Link
3. Expand the **Advanced options** section
4. Check the **Allow promotion codes** checkbox
5. Save your changes

## Next Steps

Once promo codes are enabled, you need to configure your default coupon in PromoteKit. See the [Default Coupon Code documentation](/docs/affiliate-promo-codes/default-coupon-code) for details.

---

# Integrations Overview
URL: /docs/integrations
Description: Connect PromoteKit with popular membership and payment platforms

# Overview

PromoteKit integrates with popular membership platforms to automatically track affiliate referrals when new members sign up.

## Available Integrations

  - [Memberstack](/docs/integrations/memberstack): Membership sites with Webflow and Stripe
  - [Outseta](/docs/integrations/outseta): All-in-one membership platform
  - [MemberSpace](/docs/integrations/memberspace): Turn any website into a membership site

## How Integrations Work

Each integration follows a similar pattern:

1. Add the PromoteKit tracking script to your site
2. Add a platform-specific script to capture signup events
3. When a member signs up, their email and Stripe customer ID are sent to PromoteKit
4. PromoteKit attributes the referral to the correct affiliate

> **Note:** Our [promo codes integration](/docs/affiliate-promo-codes) works with all
  these platforms with no special setup required.

---

# MemberSpace Integration
URL: /docs/integrations/memberspace
Description: Track affiliate referrals with MemberSpace membership sites

# Setup

MemberSpace lets you turn any website into a membership site. PromoteKit integrates with MemberSpace to track affiliate referrals when members sign up.

## Setup Steps

### 1. Add the PromoteKit Script

1. Go to your PromoteKit dashboard
2. Navigate to **Setup - Step 4 (PromoteKit Integration)**
3. Select **MemberSpace**
4. Copy and add the PromoteKit script to your site

### 2. Add the Signup Tracking Script

Add the following script to your member signup page. This listens for MemberSpace signup events and passes the member's email to PromoteKit:

```html
<script>
const handleMemberSignup = ({ detail }) => {
  const { memberInfo } = detail;
  window.promotekit.refer(memberInfo.email);
}
document.addEventListener('MemberSpace.member.info', handleMemberSignup);
</script>
```

### 3. Publish and Confirm

1. Publish your site
2. Return to PromoteKit and click **Ok, I've completed this**

**Note:** Referrals will only be tracked in Stripe **live mode** during testing.

---

# Memberstack Integration
URL: /docs/integrations/memberstack
Description: Track affiliate referrals with Memberstack membership sites

# Setup

Memberstack is an easy way to set up a membership site with Webflow and Stripe. PromoteKit integrates seamlessly with Memberstack to track affiliate referrals.

<iframe
  width="100%"
  style={{ aspectRatio: '16/9' }}
  src="https://www.youtube.com/embed/mW1O_SVjwoc"
  title="Memberstack integration setup"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
/>

> **Note:** Both affiliate links and promo codes work with Memberstack. Promo codes
  require no special setup.

## Setup Steps

  1. ### Get the PromoteKit Script
   
       1. Go to your PromoteKit dashboard
       2. Navigate to **Setup → Step 4 (PromoteKit Integration)**
       3. Select **Memberstack**
       4. Copy the provided script
  2. ### Add to Your Site
   
       Paste the script into your Memberstack site's `<head>` section.
  3. ### Publish and Confirm
   
       1. Publish your site
       2. Return to PromoteKit and click **Ok, I've completed this**

> **Note:** Referrals will only be tracked in Stripe **live mode**. Test mode referrals
  won't appear in your dashboard.

## Promo Codes

Our [promo codes integration](/docs/affiliate-promo-codes) also works with Memberstack with no special setup steps required. Just make sure you have promo codes enabled in your Stripe Checkout configuration.

---

# Outseta Integration
URL: /docs/integrations/outseta
Description: Track affiliate referrals with Outseta membership platform

# Setup

Outseta is an all-in-one membership platform that includes CRM, subscription billing, and authentication. PromoteKit integrates with Outseta to track affiliate referrals.

## Setup Steps

### 1. Add the PromoteKit Script

1. Go to your PromoteKit dashboard
2. Navigate to **Setup - Step 4 (PromoteKit Integration)**
3. Select **Outseta**
4. Copy and add the PromoteKit script to your site

### 2. Add the Signup Tracking Script

Add the following script to your member signup page. This listens for Outseta signup events and passes the customer's email and Stripe token to PromoteKit:

```html
<script>
Outseta.on(
  'signup',
  (account) => {
    window.promotekit.refer(
      account.PersonAccount[0].Person.Email,
      account.PaymentInformation.CustomerToken
    )
  }
);
</script>
```

### 3. Publish and Confirm

1. Publish your website
2. Return to PromoteKit and click **Ok, I've completed this**

**Note:** Referrals will only be tracked in Stripe **live mode** during testing.

---

# Payouts Overview
URL: /docs/payouts
Description: Process affiliate commission payments

# Overview

PromoteKit makes it easy to pay your affiliates their earned commissions. You can use automated batch payments or process payouts manually.

## Payout Timing

By default, PromoteKit uses **NET-15** payout terms. This means commissions are due 15 days after the start of the month. For example, commissions earned in December would be paid out on January 15.

To change your payout terms:

1. Go to **Campaign Settings** in your PromoteKit dashboard
2. Click your default campaign
3. Expand **Advanced Campaign Settings**
4. Select your preferred payout term

## Payment Methods

  - [PayPal Mass Payments](/docs/payouts/paypal-mass-payments): Pay up to 5,000 affiliates at once via PayPal
  - [Wise Batch Payments](/docs/payouts/wise-batch-payments): Pay up to 1,000 affiliates at once via Wise

## Manual Payouts

You don't have to use PayPal or Wise. You can pay affiliates through any method you prefer (bank transfer, check, crypto, etc.) and then record the payment in PromoteKit:

1. Pay the affiliate through your preferred method
2. Go to **Generate Payouts** in PromoteKit
3. Mark the payment as complete

> **Note:** Regardless of payment method, always mark payouts as complete in PromoteKit so
  your records stay accurate.

---

# PayPal Mass Payments
URL: /docs/payouts/paypal-mass-payments
Description: Pay affiliates in bulk using PayPal Mass Payments

# Overview

PayPal Mass Payments allows you to pay up to 5,000 affiliates simultaneously. PromoteKit generates a CSV file formatted specifically for PayPal's Mass Payments system.

## Prerequisites

You need a PayPal Business account with Mass Payments enabled.

  1. ### Create a PayPal Business Account
   
       If you don't have one, [create a PayPal Business account](https://www.paypal.com/business).
  2. ### Request Mass Payments Access
   
       1. Log into PayPal
       2. Click **Pay & Get Paid** in the top menu
       3. Under **Make Payments**, click **Payouts**
       4. Answer the required questions
       5. Submit your request
   
       PayPal will review and approve your request within a few business days.

## Processing Payouts

  1. ### Download the CSV
   
       When your payout cycle arrives:
   
       1. Go to the **Generate Payouts** tab in PromoteKit
       2. Click **Download Payouts** to get your CSV file
  2. ### Upload to PayPal
   
       1. Log into your PayPal Business account
       2. Navigate to Mass Payments
       3. Upload the CSV file from PromoteKit
       4. Review the payments
       5. Click **Send Payout**
  3. ### Mark as Paid in PromoteKit
   
       After PayPal processes the payments:
   
       1. Return to the **Generate Payouts** tab in PromoteKit
       2. Click **Mark all as Paid**

> **Note:** For detailed PayPal instructions, see the [PayPal Mass Payments documentation](https://www.paypal.com/us/cshelp/article/how-do-i-send-a-payouts-mass-payment-help252).

---

# Tremendous
URL: /docs/payouts/tremendous
Description: Pay affiliates with gift cards, prepaid cards, and more

# Tremendous Integration

> **Note:** Tremendous integration is coming soon. This page will be updated with detailed
  instructions once the integration is available.

## What is Tremendous?

Tremendous is a platform for sending digital rewards, including:

- Gift cards (Amazon, Visa, and 1,000+ brands)
- Prepaid Visa/Mastercard cards
- PayPal transfers
- Bank transfers (ACH)
- Venmo

## Planned Features

When the Tremendous integration launches, you'll be able to:

- Give affiliates a choice of payout method
- Automatically process payouts without manual CSV uploads
- Track payout status in real-time
- Support international affiliates with localized rewards

## Get Notified

Want to be notified when Tremendous integration launches? Contact us at hello@promotekit.com.

---

# Wise Batch Payments
URL: /docs/payouts/wise-batch-payments
Description: Pay affiliates in bulk using Wise Batch Payments

# Overview

Wise Batch Payments allows you to pay up to 1,000 affiliates at a time with low international transfer fees. PromoteKit generates a CSV file formatted specifically for Wise.

## Prerequisites

You need a Wise Business account.

  1. ### Create a Wise Business Account
   
       [Create a free Wise Business account](https://wise.com/register?profileType=BUSINESS#/email) if you don't have one.

## Processing Payouts

  1. ### Download the CSV
   
       When your payout cycle arrives:
   
       1. Go to the **Generate Payouts** tab in PromoteKit
       2. Click **Download Payouts** to get your CSV file
  2. ### Upload to Wise
   
       1. Log into your Wise Business account
       2. Navigate to Batch Payments
       3. Upload the CSV file from PromoteKit
       4. Review the payments
       5. Initiate the payout
  3. ### Mark as Paid in PromoteKit
   
       After Wise processes the payments:
   
       1. Return to the **Generate Payouts** tab in PromoteKit
       2. Click **Mark all as Paid**

> **Note:** For detailed Wise instructions, see the [Wise Batch Payments documentation](https://wise.com/help/articles/2827506/how-do-i-send-a-batch-payment).

---

# Webhooks Overview
URL: /docs/webhooks
Description: Receive real-time event notifications from PromoteKit

# Webhooks

PromoteKit sends webhook events to notify your application in real-time when things happen in your affiliate program. You can use webhooks to trigger automations, sync data to external systems, or build custom workflows.

## Setting Up Webhooks

1. Go to **Settings > Webhooks** in your PromoteKit dashboard
2. Click **Add Endpoint** to create a new webhook endpoint
3. Enter your endpoint URL (must be HTTPS)
4. Select which event types you want to receive
5. Save the endpoint

You can manage your endpoints, view delivery logs, and retry failed deliveries from the Webhooks settings page.

## Event Types

PromoteKit sends the following webhook events:

| Event                | Description                                                                      |
| -------------------- | -------------------------------------------------------------------------------- |
| `affiliate.created`  | A new affiliate is created (from the dashboard, API, or affiliate portal signup) |
| `affiliate.approved` | An affiliate is approved (individually or via bulk approval)                     |
| `referral.created`   | A new referral is tracked (from Stripe, the dashboard, API, or tracking script)  |
| `referral.converted` | A referral receives their first commission (first paid conversion)               |
| `commission.created` | A new commission is generated (from Stripe payments, the dashboard, or API)      |

## Payload Format

All webhook events are sent as HTTP POST requests with a JSON body. The payload has the following structure:

```json
{
  "type": "affiliate.created",
  "data": {
    // The resource object in the same format as the API
  }
}
```

The `data` field contains the resource object in the **same format as the corresponding API endpoint**. For example, an `affiliate.created` event contains the same affiliate object you would get from the [GET /affiliates/:id](/docs/api-reference/affiliates/get-affiliate) API endpoint.

### affiliate.created / affiliate.approved

```json
{
  "type": "affiliate.created",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "affiliate@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "payout_email": "jane@example.com",
    "links": [
      {
        "url": "https://yoursite.com?via=jane",
        "code": "jane"
      }
    ],
    "promo_codes": [
      {
        "code": "JANE20",
        "external_id": "promo_abc123"
      }
    ],
    "clicks": 0,
    "approved": true,
    "banned": false,
    "details": null,
    "new_paid_referral_notifications": true,
    "created_at": "2025-01-15T10:30:00Z",
    "campaign": {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Default Campaign",
      "commission_type": "percentage",
      "commission_amount": 20
    }
  }
}
```

### referral.created / referral.converted

```json
{
  "type": "referral.created",
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "email": "customer@example.com",
    "subscription_status": "signed_up",
    "signup_date": "2025-01-20T14:00:00Z",
    "stripe_customer_id": "cus_abc123",
    "created_at": "2025-01-20T14:00:00Z",
    "affiliate": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "affiliate@example.com",
      "first_name": "Jane",
      "last_name": "Doe"
    }
  }
}
```

### commission.created

```json
{
  "type": "commission.created",
  "data": {
    "id": "880e8400-e29b-41d4-a716-446655440003",
    "revenue_amount": 99.0,
    "currency": "USD",
    "commission_amount": 19.8,
    "payout_status": "not_paid",
    "referral_date": "2025-01-20T14:00:00Z",
    "created_at": "2025-01-20T14:00:00Z",
    "stripe_payment_id": "pi_abc123",
    "affiliate": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "affiliate@example.com",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "referral": {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "email": "customer@example.com",
      "subscription_status": "active",
      "signup_date": "2025-01-20T14:00:00Z",
      "stripe_customer_id": "cus_abc123",
      "created_at": "2025-01-20T14:00:00Z"
    },
    "payout": null
  }
}
```

## Verifying Webhook Signatures

PromoteKit signs all webhook payloads so you can verify they are authentic. Each webhook request includes the following headers:

| Header           | Description                                    |
| ---------------- | ---------------------------------------------- |
| `svix-id`        | Unique message identifier                      |
| `svix-timestamp` | Unix timestamp of when the message was created |
| `svix-signature` | The signature(s) for the payload               |

### Finding Your Signing Secret

1. Go to **Settings > Webhooks** in your dashboard
2. Click on your endpoint
3. Click **Signing Secret** to reveal your endpoint's secret

The secret starts with `whsec_`.

### Verifying with the Svix Library (Recommended)

Install the Svix library for your language:

<Tabs items={['JavaScript', 'Python']}>
<Tab value="JavaScript">
```bash
npm install svix
```
</Tab>
<Tab value="Python">
```bash
pip install svix
```
</Tab>
</Tabs>

Then verify the webhook:

<Tabs items={["JavaScript", "Python"]}>
<Tab value="JavaScript">
```javascript

const secret = "whsec_your_secret_here";
const wh = new Webhook(secret);

// In your webhook handler:
app.post("/webhook", (req, res) => {
  const headers = req.headers;
  const payload = req.body; // Must be the raw request body string

  try {
    const event = wh.verify(payload, headers);
    // Process the verified event
    console.log("Event type:", event.type);
    console.log("Event data:", event.data);
  } catch (err) {
    console.error("Webhook verification failed:", err);
    return res.status(400).send("Invalid signature");
  }

  res.status(200).send("OK");
});
```
</Tab>
<Tab value="Python">
```python
from svix.webhooks import Webhook

secret = "whsec_your_secret_here"
wh = Webhook(secret)

# In your webhook handler:
headers = request.headers
payload = request.body  # Must be the raw request body

try:
    event = wh.verify(payload, headers)
    # Process the verified event
    print("Event type:", event["type"])
except Exception as e:
    print("Webhook verification failed:", e)
    return Response(status=400)
```

</Tab>
</Tabs>

> **Warning:** You must use the **raw request body** when verifying webhooks. If your
  framework automatically parses JSON, you need to capture the raw body before
  parsing.

### Manual Verification

If you prefer to verify manually, the signature is computed as an HMAC-SHA256 of the message ID, timestamp, and body:

```
signed_content = "${svix_id}.${svix_timestamp}.${body}"
signature = base64(hmac_sha256(base64_decode(secret), signed_content))
```

Compare your computed signature against the one in the `svix-signature` header (after the `v1,` prefix).

## Retry Behavior

If your endpoint returns a non-2xx status code, PromoteKit will retry the delivery with exponential backoff. You can view delivery attempts and manually retry failed deliveries from the **Settings > Webhooks** page in your dashboard.

## Best Practices

- **Respond quickly**: Return a 2xx status code within 15 seconds. Process the event asynchronously if needed.
- **Handle duplicates**: Webhook deliveries may be retried. Use the `svix-id` header to deduplicate.
- **Verify signatures**: Always verify the webhook signature before processing events.
- **Use HTTPS**: Webhook endpoints must use HTTPS.

---

---

---



---

# API Reference

---



---

Base URL: https://www.promotekit.com/api/v1

---

Authentication: Bearer token in the Authorization header.

---



---

# Introduction
URL: /docs/api-reference
Description: Welcome to the PromoteKit API documentation

# Overview

The PromoteKit API enables you to programmatically manage your affiliate program, including affiliates, campaigns, referrals, commissions, and payouts. The API follows RESTful principles and uses standard HTTP methods. All requests and responses use JSON format.

## Base URL

All API requests should be made to:

```
https://www.promotekit.com/api/v1
```

## Authentication

All API endpoints require authentication using Bearer token authentication. Include your API key in the Authorization header:

```
Authorization: Bearer <API_KEY>
```

You can create API keys in [Dashboard Settings → API Keys](https://promotekit.com/dashboard).

## Response Format

All responses are returned in JSON format and include a `success` boolean indicating if the request was successful.

### Success Response

```json
{
  "success": true,
  "data": { ... }
}
```

### Error Response

```json
{
  "success": false,
  "error": {
    "message": "Error description",
    "type": "error_type"
  }
}
```

## Rate Limiting

API requests are limited to **200 requests per minute** per API key. If you exceed this limit, you'll receive a `429 Too Many Requests` response.

## Pagination

List endpoints support pagination using `limit` and `page` parameters:

- `limit` - Number of records to return (default: 10, max: 100)
- `page` - Page number, 1-indexed (default: 1)

Paginated responses include:

```json
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total_count": 45,
    "total_pages": 5,
    "has_more": true
  }
}
```

---

# Create affiliate
URL: /docs/api-reference/affiliates/create-affiliate
Description: Creates a new affiliate in your organization.

**POST** `https://www.promotekit.com/api/v1/affiliates`

Creates a new affiliate in your organization.

## Authentication

Requires a Bearer token in the `Authorization` header.

## Request Body

- `email`: string (email) **(required)** - Affiliate email (required)
- `first_name`: string **(required)** - First name
- `last_name`: string **(required)** - Last name
- `payout_email`: string (email) - Payout email address
- `ref_code`: string - Unique code that goes at the end of the affiliate link
- `promo_code`: string - Stripe promo code (will be generated if it doesn't already exist in Stripe)
- `campaign_id`: string (uuid) - Campaign UUID (uses default if not provided)
- `approved`: boolean - Whether to approve the affiliate to start promoting immediately
- `details`: string - Additional details
- `new_paid_referral_notifications`: boolean - Whether the affiliate receives email alerts when they make a new paid referral

## Responses

### 200 - Affiliate created

- `success`: boolean **(required)**
- `data`: object **(required)**

### 400 - Invalid request

- `success`: boolean **(required)**
- `error`: object **(required)**

### 401 - Authentication failed

- `success`: boolean **(required)**
- `error`: object **(required)**

### 429 - Rate limit exceeded

- `success`: boolean **(required)**
- `error`: object **(required)**

---

# Get affiliate
URL: /docs/api-reference/affiliates/get-affiliate
Description: Retrieves a single affiliate by UUID.

**GET** `https://www.promotekit.com/api/v1/affiliates/{id}`

Retrieves a single affiliate by UUID.

## Authentication

Requires a Bearer token in the `Authorization` header.

## Parameters

- `id` (path): string (uuid) **(required)** - Resource UUID

## Responses

### 200 - Successful response

- `success`: boolean **(required)**
- `data`: object **(required)**

### 400 - Invalid request

- `success`: boolean **(required)**
- `error`: object **(required)**

### 401 - Authentication failed

- `success`: boolean **(required)**
- `error`: object **(required)**

### 404 - Resource not found

- `success`: boolean **(required)**
- `error`: object **(required)**

### 429 - Rate limit exceeded

- `success`: boolean **(required)**
- `error`: object **(required)**

---

# List affiliates
URL: /docs/api-reference/affiliates/list-affiliates
Description: Returns a paginated list of affiliates in your organization.

**GET** `https://www.promotekit.com/api/v1/affiliates`

Returns a paginated list of affiliates in your organization.

## Authentication

Requires a Bearer token in the `Authorization` header.

## Parameters

- `campaign_id` (query): string (uuid) - Filter by campaign UUID
- `email` (query): string (email) - Filter by affiliate email. Returns 0 or 1 results.
- `ref_code` (query): string - Filter by affiliate link referral code (unique code at the end of the affiliate's link).
- `promo_code` (query): string - Filter by affiliate promo code.
- `limit` (query): integer (default: 10) - Number of records to return (default: 10, max: 100)
- `page` (query): integer (default: 1) - Page number (1-indexed)

## Responses

### 200 - Successful response

- `success`: boolean **(required)**
- `data`: array **(required)**
- `pagination`: object **(required)**

### 401 - Authentication failed

- `success`: boolean **(required)**
- `error`: object **(required)**

### 429 - Rate limit exceeded

- `success`: boolean **(required)**
- `error`: object **(required)**

---

# Update affiliate
URL: /docs/api-reference/affiliates/update-affiliate
Description: Updates an existing affiliate.

**PUT** `https://www.promotekit.com/api/v1/affiliates/{id}`

Updates an existing affiliate.

## Authentication

Requires a Bearer token in the `Authorization` header.

## Parameters

- `id` (path): string (uuid) **(required)** - Resource UUID

## Request Body

- `email`: string (email) - Affiliate email
- `first_name`: string - First name
- `last_name`: string - Last name
- `payout_email`: string (email) - Payout email address
- `ref_code`: string - Unique code that goes at the end of the affiliate link
- `promo_code`: string - Stripe promo code (will be generated if it doesn't already exist in Stripe)
- `campaign_id`: string (uuid) - Campaign UUID to assign the affiliate to
- `approved`: boolean - Whether the affiliate has been approved to start promoting
- `banned`: boolean - Whether the affiliate is banned. Banned affiliates are not eligible for future commissions and payouts.
- `details`: string - Additional details
- `new_paid_referral_notifications`: boolean - Whether the affiliate receives email alerts when they make a new paid referral

## Responses

### 200 - Affiliate updated

- `success`: boolean **(required)**
- `data`: object **(required)**

### 400 - Invalid request

- `success`: boolean **(required)**
- `error`: object **(required)**

### 401 - Authentication failed

- `success`: boolean **(required)**
- `error`: object **(required)**

### 404 - Resource not found

- `success`: boolean **(required)**
- `error`: object **(required)**

### 429 - Rate limit exceeded

- `success`: boolean **(required)**
- `error`: object **(required)**

---

# Create campaign
URL: /docs/api-reference/campaigns/create-campaign
Description: Creates a new campaign in your organization.

**POST** `https://www.promotekit.com/api/v1/campaigns`

Creates a new campaign in your organization.

## Authentication

Requires a Bearer token in the `Authorization` header.

## Request Body

- `name`: string **(required)** - Campaign name (for internal use, affiliates do not see this name)
- `commission_type`: string: `percentage`, `fixed` **(required)** - Whether the campaign gives percentage based or fixed amount commissions
- `commission_amount`: number **(required)** - Percentage or fixed amount commission rate (e.g. 20 would mean 20% or $20)
- `code_mode`: string: `link`, `coupon`, `both` **(required)** - Referral code type. "link" creates affiliate links, "coupon" creates promo codes, "both" creates both.
- `website_url`: string - Campaign website URL. Required when code_mode is "link" or "both".
- `reference_coupon`: string - Stripe coupon ID that's used to create affiliate promo codes. Required when code_mode is "coupon" or "both".
- `is_default`: boolean

## Responses

### 200 - Campaign created

- `success`: boolean **(required)**
- `data`: object **(required)**

### 400 - Invalid request

- `success`: boolean **(required)**
- `error`: object **(required)**

### 401 - Authentication failed

- `success`: boolean **(required)**
- `error`: object **(required)**

### 429 - Rate limit exceeded

- `success`: boolean **(required)**
- `error`: object **(required)**

---

# Get campaign
URL: /docs/api-reference/campaigns/get-campaign
Description: Retrieves a single campaign by UUID.

**GET** `https://www.promotekit.com/api/v1/campaigns/{id}`

Retrieves a single campaign by UUID.

## Authentication

Requires a Bearer token in the `Authorization` header.

## Parameters

- `id` (path): string (uuid) **(required)** - Resource UUID

## Responses

### 200 - Successful response

- `success`: boolean **(required)**
- `data`: object **(required)**

### 400 - Invalid request

- `success`: boolean **(required)**
- `error`: object **(required)**

### 401 - Authentication failed

- `success`: boolean **(required)**
- `error`: object **(required)**

### 404 - Resource not found

- `success`: boolean **(required)**
- `error`: object **(required)**

### 429 - Rate limit exceeded

- `success`: boolean **(required)**
- `error`: object **(required)**

---

# List campaigns
URL: /docs/api-reference/campaigns/list-campaigns
Description: Returns a paginated list of campaigns in your organization.

**GET** `https://www.promotekit.com/api/v1/campaigns`

Returns a paginated list of campaigns in your organization.

## Authentication

Requires a Bearer token in the `Authorization` header.

## Parameters

- `limit` (query): integer (default: 10) - Number of records to return (default: 10, max: 100)
- `page` (query): integer (default: 1) - Page number (1-indexed)

## Responses

### 200 - Successful response

- `success`: boolean **(required)**
- `data`: array **(required)**
- `pagination`: object **(required)**

### 401 - Authentication failed

- `success`: boolean **(required)**
- `error`: object **(required)**

### 429 - Rate limit exceeded

- `success`: boolean **(required)**
- `error`: object **(required)**

---

# Update campaign
URL: /docs/api-reference/campaigns/update-campaign
Description: Updates an existing campaign.

**PUT** `https://www.promotekit.com/api/v1/campaigns/{id}`

Updates an existing campaign.

## Authentication

Requires a Bearer token in the `Authorization` header.

## Parameters

- `id` (path): string (uuid) **(required)** - Resource UUID

## Request Body

- `name`: string
- `commission_type`: string: `percentage`, `fixed`
- `commission_amount`: number
- `code_mode`: string: `link`, `coupon`, `both` - Referral code mode. "link" creates affiliate links, "coupon" creates promo codes, "both" creates both.
- `website_url`: string - Campaign website URL. Required when code_mode is "link" or "both".
- `reference_coupon`: string - Stripe coupon ID for the campaign. Required when code_mode is "coupon" or "both".
- `is_default`: boolean

## Responses

### 200 - Campaign updated

- `success`: boolean **(required)**
- `data`: object **(required)**

### 400 - Invalid request

- `success`: boolean **(required)**
- `error`: object **(required)**

### 401 - Authentication failed

- `success`: boolean **(required)**
- `error`: object **(required)**

### 404 - Resource not found

- `success`: boolean **(required)**
- `error`: object **(required)**

### 429 - Rate limit exceeded

- `success`: boolean **(required)**
- `error`: object **(required)**

---

# Create commission
URL: /docs/api-reference/commissions/create-commission
Description: Manually creates a commission for a referral.

**POST** `https://www.promotekit.com/api/v1/commissions`

Manually creates a commission for a referral.

## Authentication

Requires a Bearer token in the `Authorization` header.

## Request Body

- `referral_id`: string (uuid) **(required)** - UUID of the referral this commission is for (required)
- `revenue_amount`: number **(required)** - Transaction/revenue amount (required, must be greater than 0)
- `commission_amount`: number **(required)** - Commission earned (required, must be greater than 0)
- `referral_date`: string (date-time) - Date of the referral (defaults to now)
- `stripe_payment_id`: string - Stripe payment ID reference

## Responses

### 200 - Commission created

- `success`: boolean **(required)**
- `data`: object **(required)**

### 400 - Invalid request

- `success`: boolean **(required)**
- `error`: object **(required)**

### 401 - Authentication failed

- `success`: boolean **(required)**
- `error`: object **(required)**

### 429 - Rate limit exceeded

- `success`: boolean **(required)**
- `error`: object **(required)**

---

# Get commission
URL: /docs/api-reference/commissions/get-commission
Description: Retrieves a single commission by UUID.

**GET** `https://www.promotekit.com/api/v1/commissions/{id}`

Retrieves a single commission by UUID.

## Authentication

Requires a Bearer token in the `Authorization` header.

## Parameters

- `id` (path): string (uuid) **(required)** - Resource UUID

## Responses

### 200 - Successful response

- `success`: boolean **(required)**
- `data`: object **(required)**

### 400 - Invalid request

- `success`: boolean **(required)**
- `error`: object **(required)**

### 401 - Authentication failed

- `success`: boolean **(required)**
- `error`: object **(required)**

### 404 - Resource not found

- `success`: boolean **(required)**
- `error`: object **(required)**

### 429 - Rate limit exceeded

- `success`: boolean **(required)**
- `error`: object **(required)**

---

# List commissions
URL: /docs/api-reference/commissions/list-commissions
Description: Returns a paginated list of commission records in your organization.

**GET** `https://www.promotekit.com/api/v1/commissions`

Returns a paginated list of commission records in your organization.

## Authentication

Requires a Bearer token in the `Authorization` header.

## Parameters

- `affiliate_id` (query): string (uuid) - Filter by affiliate UUID
- `payout_status` (query): string - one of: `not_paid`, `paid` - Filter by payout status
- `payout_id` (query): string (uuid) - Filter by payout UUID. Returns only commissions included in the specified payout.
- `limit` (query): integer (default: 10) - Number of records to return (default: 10, max: 100)
- `page` (query): integer (default: 1) - Page number (1-indexed)

## Responses

### 200 - Successful response

- `success`: boolean **(required)**
- `data`: array **(required)**
- `pagination`: object **(required)**

### 401 - Authentication failed

- `success`: boolean **(required)**
- `error`: object **(required)**

### 429 - Rate limit exceeded

- `success`: boolean **(required)**
- `error`: object **(required)**

---

# Get payout
URL: /docs/api-reference/payouts/get-payout
Description: Retrieves a single payout by UUID.

**GET** `https://www.promotekit.com/api/v1/payouts/{id}`

Retrieves a single payout by UUID.

## Authentication

Requires a Bearer token in the `Authorization` header.

## Parameters

- `id` (path): string (uuid) **(required)** - Resource UUID

## Responses

### 200 - Successful response

- `success`: boolean **(required)**
- `data`: object **(required)**

### 400 - Invalid request

- `success`: boolean **(required)**
- `error`: object **(required)**

### 401 - Authentication failed

- `success`: boolean **(required)**
- `error`: object **(required)**

### 404 - Resource not found

- `success`: boolean **(required)**
- `error`: object **(required)**

### 429 - Rate limit exceeded

- `success`: boolean **(required)**
- `error`: object **(required)**

---

# List payouts
URL: /docs/api-reference/payouts/list-payouts
Description: Returns a paginated list of payouts in your organization.

**GET** `https://www.promotekit.com/api/v1/payouts`

Returns a paginated list of payouts in your organization.

## Authentication

Requires a Bearer token in the `Authorization` header.

## Parameters

- `affiliate_id` (query): string (uuid) - Filter by affiliate UUID
- `limit` (query): integer (default: 10) - Number of records to return (default: 10, max: 100)
- `page` (query): integer (default: 1) - Page number (1-indexed)

## Responses

### 200 - Successful response

- `success`: boolean **(required)**
- `data`: array **(required)**
- `pagination`: object **(required)**

### 401 - Authentication failed

- `success`: boolean **(required)**
- `error`: object **(required)**

### 429 - Rate limit exceeded

- `success`: boolean **(required)**
- `error`: object **(required)**

---

# Create referral
URL: /docs/api-reference/referrals/create-referral
Description: Creates a new referral for an affiliate in your organization.

**POST** `https://www.promotekit.com/api/v1/referrals`

Creates a new referral for an affiliate in your organization.

## Authentication

Requires a Bearer token in the `Authorization` header.

## Request Body

- `affiliate_id`: string (uuid) **(required)** - UUID of the affiliate this referral belongs to
- `email`: string (email) **(required)** - Email address of the referred customer
- `stripe_customer_id`: string - Stripe customer ID of the referred customer
- `subscription_status`: string: `active`, `signed_up`, `trialing`, `canceled`, `past_due` - Subscription status of the referred customer

## Responses

### 200 - Successful response

- `success`: boolean **(required)**
- `data`: object **(required)**

### 400 - Invalid request

- `success`: boolean **(required)**
- `error`: object **(required)**

### 401 - Authentication failed

- `success`: boolean **(required)**
- `error`: object **(required)**

### 429 - Rate limit exceeded

- `success`: boolean **(required)**
- `error`: object **(required)**

---

# List referrals
URL: /docs/api-reference/referrals/list-referrals
Description: Returns a paginated list of referred customers.

**GET** `https://www.promotekit.com/api/v1/referrals`

Returns a paginated list of referrals (referred users) in your organization.

## Authentication

Requires a Bearer token in the `Authorization` header.

## Parameters

- `affiliate_id` (query): string (uuid) - Filter by affiliate UUID
- `email` (query): string (email) - Filter by referred customer email (exact match)
- `stripe_customer_id` (query): string - Filter by Stripe customer ID
- `subscription_status` (query): string - Filter by subscription status. Possible values: `signed_up`, `active`, `trialing`, `canceled`, `past_due`. Pass a comma-separated list to filter by multiple statuses (e.g. `?subscription_status=active,trialing`).
- `limit` (query): integer (default: 10) - Number of records to return (default: 10, max: 100)
- `page` (query): integer (default: 1) - Page number (1-indexed)

## Responses

### 200 - Successful response

- `success`: boolean **(required)**
- `data`: array **(required)**
- `pagination`: object **(required)**

### 401 - Authentication failed

- `success`: boolean **(required)**
- `error`: object **(required)**

### 429 - Rate limit exceeded

- `success`: boolean **(required)**
- `error`: object **(required)**