rewardful

List the affiliate program's campaigns with their reward rules (percent or fixed commission, payout minimum, referral expiry) and totals (visitors, leads, conversions, affiliates). Rewardful: GET /v1/campaigns.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, from 1. See pagination.next_page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Fetch a single campaign by id. Rewardful: GET /v1/campaigns/:id.

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "description": "The campaign's id (UUID)."
    }
  },
  "required": [
    "campaign_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List affiliates, newest first, with visitors/leads/conversions. Filter by campaign, or look one up by email or Stripe customer id (returns zero or one). Expand campaign, links or commission_stats for more detail. Rewardful: GET /v1/affiliates.

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "description": "Only affiliates in this campaign.",
      "type": "string"
    },
    "email": {
      "description": "Only the affiliate with this email.",
      "type": "string"
    },
    "stripe_customer_id": {
      "description": "Only the customer-referrer affiliate tied to this Stripe customer (cus_...).",
      "type": "string"
    },
    "expand": {
      "description": "Nested objects to include for each affiliate.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "campaign",
          "links",
          "commission_stats"
        ]
      }
    },
    "page": {
      "description": "Page number, from 1. See pagination.next_page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Fetch a single affiliate by id, including their campaign, links, coupon and visitor/lead/conversion counts. Rewardful: GET /v1/affiliates/:id.

{
  "type": "object",
  "properties": {
    "affiliate_id": {
      "type": "string",
      "minLength": 1,
      "description": "The affiliate's id (UUID)."
    }
  },
  "required": [
    "affiliate_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List affiliate links (URL, token, visitors, leads, conversions, affiliate_id), newest first. Rewardful: GET /v1/affiliate_links.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, from 1. See pagination.next_page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Fetch a single affiliate link by id. Rewardful: GET /v1/affiliate_links/:id.

{
  "type": "object",
  "properties": {
    "link_id": {
      "type": "string",
      "minLength": 1,
      "description": "The affiliate link's id (UUID)."
    }
  },
  "required": [
    "link_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List affiliate coupon / promotion codes (token, Stripe id, leads, conversions, archived), optionally for one affiliate. Rewardful: GET /v1/affiliate_coupons.

{
  "type": "object",
  "properties": {
    "affiliate_id": {
      "description": "Only this affiliate's coupons.",
      "type": "string"
    },
    "page": {
      "description": "Page number, from 1. See pagination.next_page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Fetch a single affiliate coupon by id. Rewardful: GET /v1/affiliate_coupons/:id.

{
  "type": "object",
  "properties": {
    "coupon_id": {
      "type": "string",
      "minLength": 1,
      "description": "The affiliate coupon's id (UUID)."
    }
  },
  "required": [
    "coupon_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List referrals — visitors who arrived via an affiliate link — newest first, with their conversion state (visitor, lead, conversion), customer and link. Filter by affiliate, state, email, Stripe customer or an updated-at window. Rewardful: GET /v1/referrals.

{
  "type": "object",
  "properties": {
    "affiliate_id": {
      "description": "Only this affiliate's referrals.",
      "type": "string"
    },
    "conversion_state": {
      "description": "Only referrals currently in these conversion states.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "visitor",
          "lead",
          "conversion"
        ]
      }
    },
    "email": {
      "description": "Only referrals with this customer email.",
      "type": "string"
    },
    "stripe_customer_id": {
      "description": "Only referrals with this Stripe customer (cus_...).",
      "type": "string"
    },
    "updated_since": {
      "description": "ISO 8601 timestamp: only referrals updated after it.",
      "type": "string"
    },
    "updated_until": {
      "description": "ISO 8601 timestamp: only referrals updated before it.",
      "type": "string"
    },
    "expand": {
      "description": "Include the full affiliate object for each referral.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "affiliate"
        ]
      }
    },
    "page": {
      "description": "Page number, from 1. See pagination.next_page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List commissions (rewards owed for referred customers' payments) newest first, with amount in cents, currency and state (pending, due, paid, voided). Filter by affiliate or state; expand the sale (with referral, customer and affiliate) or campaign. Rewardful: GET /v1/commissions.

{
  "type": "object",
  "properties": {
    "affiliate_id": {
      "description": "Only this affiliate's commissions.",
      "type": "string"
    },
    "state": {
      "description": "Only commissions in these states.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "pending",
          "due",
          "paid",
          "voided"
        ]
      }
    },
    "expand": {
      "description": "Nested objects to include for each commission.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "sale",
          "campaign"
        ]
      }
    },
    "page": {
      "description": "Page number, from 1. See pagination.next_page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Fetch a single commission by id, with its campaign and the sale (charge, refund and tax amounts, referral, customer, affiliate) that earned it. Rewardful: GET /v1/commissions/:id.

{
  "type": "object",
  "properties": {
    "commission_id": {
      "type": "string",
      "minLength": 1,
      "description": "The commission's id (UUID)."
    }
  },
  "required": [
    "commission_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List payouts — bundles of an affiliate's payable commissions — newest first, with amount, currency and state (pending, due, processing, paid). Filter by affiliate or state; expand affiliate or commissions. Rewardful: GET /v1/payouts.

{
  "type": "object",
  "properties": {
    "affiliate_id": {
      "description": "Only this affiliate's payouts.",
      "type": "string"
    },
    "state": {
      "description": "Only payouts in these states.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "pending",
          "due",
          "processing",
          "paid"
        ]
      }
    },
    "expand": {
      "description": "Nested objects to include for each payout.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "affiliate",
          "commissions"
        ]
      }
    },
    "page": {
      "description": "Page number, from 1. See pagination.next_page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Fetch a single payout by id, with the affiliate and the commissions it bundles. Rewardful: GET /v1/payouts/:id.

{
  "type": "object",
  "properties": {
    "payout_id": {
      "type": "string",
      "minLength": 1,
      "description": "The payout's id (UUID)."
    }
  },
  "required": [
    "payout_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Create a new affiliate campaign with its reward rule. For reward_type percent pass commission_percent; for amount pass commission_amount_cents and commission_amount_currency. Rewardful: POST /v1/campaigns.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "The campaign's name."
    },
    "url": {
      "type": "string",
      "format": "uri",
      "description": "Base URL used to build affiliate links, e.g. https://example.com."
    },
    "private": {
      "description": "true = invite-only; false = anyone can sign up.",
      "type": "boolean"
    },
    "reward_type": {
      "type": "string",
      "enum": [
        "percent",
        "amount"
      ],
      "description": "Percent of each sale, or a fixed amount."
    },
    "commission_percent": {
      "description": "Commission percentage. Required when reward_type is percent.",
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "commission_amount_cents": {
      "description": "Fixed commission in cents. Required when reward_type is amount.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "commission_amount_currency": {
      "description": "ISO currency code of the fixed commission, e.g. USD. Required when reward_type is amount.",
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    },
    "minimum_payout_cents": {
      "description": "Minimum cumulative commissions before a payout, in cents of the company's display currency.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "stripe_coupon_id": {
      "description": "Stripe coupon for double-sided incentives. Growth/Enterprise plans only.",
      "type": "string"
    }
  },
  "required": [
    "name",
    "url",
    "reward_type"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Change a campaign's name, URL, visibility, reward rule, payout minimum or coupon. Only the fields you pass change. Rewardful: PUT /v1/campaigns/:id.

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "description": "The campaign's id (UUID)."
    },
    "name": {
      "description": "The campaign's name.",
      "type": "string",
      "minLength": 1
    },
    "url": {
      "type": "string",
      "format": "uri",
      "description": "Base URL used to build affiliate links, e.g. https://example.com."
    },
    "private": {
      "description": "true = invite-only; false = anyone can sign up.",
      "type": "boolean"
    },
    "reward_type": {
      "type": "string",
      "enum": [
        "percent",
        "amount"
      ],
      "description": "Percent of each sale, or a fixed amount."
    },
    "commission_percent": {
      "description": "Commission percentage. Required when reward_type is percent.",
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "commission_amount_cents": {
      "description": "Fixed commission in cents. Required when reward_type is amount.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "commission_amount_currency": {
      "description": "ISO currency code of the fixed commission, e.g. USD. Required when reward_type is amount.",
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    },
    "minimum_payout_cents": {
      "description": "Minimum cumulative commissions before a payout, in cents of the company's display currency.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "stripe_coupon_id": {
      "description": "Stripe coupon for double-sided incentives. Growth/Enterprise plans only.",
      "type": "string"
    }
  },
  "required": [
    "campaign_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Add an affiliate (or a customer referrer, by passing stripe_customer_id). Rewardful sends NO welcome email for API-created affiliates. Rewardful: POST /v1/affiliates.

{
  "type": "object",
  "properties": {
    "first_name": {
      "type": "string",
      "minLength": 1,
      "description": "First name."
    },
    "last_name": {
      "type": "string",
      "minLength": 1,
      "description": "Last name."
    },
    "email": {
      "type": "string",
      "minLength": 3,
      "description": "Email address."
    },
    "token": {
      "type": "string",
      "pattern": "^[A-Za-z0-9-]+$",
      "description": "Link token, e.g. `jb007` for ?via=jb007. Letters, numbers and dashes only."
    },
    "state": {
      "type": "string",
      "enum": [
        "active",
        "disabled",
        "suspicious"
      ],
      "description": "Affiliate state. Disabled/suspicious affiliates stop tracking and earning and can't log in."
    },
    "campaign_id": {
      "description": "Campaign to put the affiliate in (default campaign if omitted on create).",
      "type": "string"
    },
    "paypal_email": {
      "description": "PayPal address commissions should be paid to.",
      "type": "string"
    },
    "wise_email": {
      "description": "Wise address commissions should be paid to.",
      "type": "string"
    },
    "stripe_customer_id": {
      "description": "Customer-referral programs only: the live-mode Stripe customer that receives account credits.",
      "type": "string"
    },
    "receive_new_commission_notifications": {
      "description": "Email the affiliate when they earn a commission (default true).",
      "type": "boolean"
    }
  },
  "required": [
    "first_name",
    "last_name",
    "email"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Change an affiliate's name, email, payout emails, notifications, campaign (moves them) or state. Setting state to disabled stops tracking and earning; set it back to active to undo. Rewardful: PUT /v1/affiliates/:id.

{
  "type": "object",
  "properties": {
    "affiliate_id": {
      "type": "string",
      "minLength": 1,
      "description": "The affiliate's id (UUID)."
    },
    "first_name": {
      "description": "First name.",
      "type": "string",
      "minLength": 1
    },
    "last_name": {
      "description": "Last name.",
      "type": "string",
      "minLength": 1
    },
    "email": {
      "description": "Email address.",
      "type": "string",
      "minLength": 3
    },
    "state": {
      "type": "string",
      "enum": [
        "active",
        "disabled",
        "suspicious"
      ],
      "description": "Affiliate state. Disabled/suspicious affiliates stop tracking and earning and can't log in."
    },
    "campaign_id": {
      "description": "Campaign to put the affiliate in (default campaign if omitted on create).",
      "type": "string"
    },
    "paypal_email": {
      "description": "PayPal address commissions should be paid to.",
      "type": "string"
    },
    "wise_email": {
      "description": "Wise address commissions should be paid to.",
      "type": "string"
    },
    "stripe_customer_id": {
      "description": "Customer-referral programs only: the live-mode Stripe customer that receives account credits.",
      "type": "string"
    },
    "receive_new_commission_notifications": {
      "description": "Email the affiliate when they earn a commission (default true).",
      "type": "boolean"
    }
  },
  "required": [
    "affiliate_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Give an affiliate an additional tracking link. A token is generated if omitted. Growth/Enterprise plans only. Rewardful: POST /v1/affiliate_links.

{
  "type": "object",
  "properties": {
    "affiliate_id": {
      "type": "string",
      "minLength": 1,
      "description": "The affiliate's id (UUID)."
    },
    "token": {
      "type": "string",
      "pattern": "^[A-Za-z0-9-]+$",
      "description": "Link token, e.g. `jb007` for ?via=jb007. Letters, numbers and dashes only."
    }
  },
  "required": [
    "affiliate_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Change the token of an existing affiliate link. WARNING: the old token stops tracking immediately — links already shared with it break. Prefer rewardful_create_affiliate_link to add a second token. Rewardful: PUT /v1/affiliate_links/:id.

{
  "type": "object",
  "properties": {
    "link_id": {
      "type": "string",
      "minLength": 1,
      "description": "The affiliate link's id (UUID)."
    },
    "token": {
      "type": "string",
      "pattern": "^[A-Za-z0-9-]+$",
      "description": "Link token, e.g. `jb007` for ?via=jb007. Letters, numbers and dashes only."
    }
  },
  "required": [
    "link_id",
    "token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Assign a coupon / promotion code to an affiliate so sales using it are credited to them. The code must match one defined in Stripe, and the affiliate's campaign must have a campaign coupon set in the dashboard. Rewardful: POST /v1/affiliate_coupons.

{
  "type": "object",
  "properties": {
    "affiliate_id": {
      "type": "string",
      "minLength": 1,
      "description": "The affiliate's id (UUID)."
    },
    "token": {
      "type": "string",
      "minLength": 1,
      "description": "The exact coupon / promotion code as defined in Stripe, e.g. MYCODE."
    }
  },
  "required": [
    "affiliate_id",
    "token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}