Referral Channels

A referral channel is a coupon code that you own and can share with other users. When another user applies the channel's code and makes a paid purchase, they receive the configured discount and you accrue a referral credit for the commission. Each channel can be configured for one-time-only discounts (first purchase only) or recurring discounts (every renewal).

Channels are created and configured by the Webshare team. This endpoint lists the channels that belong to the authenticated user along with aggregate usage statistics.

The referral channel object

Attributes	Type	Description
`id`	`integer`	Unique identifier of the referral channel.
`code`	`string`	The coupon code other users apply to receive the discount. Case-insensitive when matched.
`description`	`string`	Human-readable description of the channel. May be an empty string.
`promo_type`	`string`	Type of discount. Either `percent_off` or `value_off`.
`promo_value`	`decimal`	Magnitude of the discount. For `percent_off` this is a value between 0 and 1 (e.g. `0.20` for 20% off). For `value_off` this is an absolute USD amount.
`is_active`	`boolean`	If `false`, the code can no longer be applied by new users.
`is_recurring`	`boolean`	If `true`, the discount applies to every renewal of the redeemer's plan. If `false`, only to the first purchase.
`start_date`	`datetime`	Timestamp from which the code becomes applicable.
`end_date`	`datetime`	Timestamp after which the code can no longer be applied. May be `null` if the channel does not expire.
`total_uses`	`integer`	Total number of distinct redemptions of this channel across all users.
`total_commission`	`float`	Total USD commission earned through this channel.
`total_revenue`	`float`	Total USD revenue generated by redeemers of this channel — sum of paid transaction amounts (net of refunds) across all redemptions. Uses the same attribution rule as `total_uses`: transactions from users referred via a different affiliate's link are excluded.
`initial_rate`	`decimal`	Commission rate (0 to 1) applied to a referred user's transactions during the initial period. E.g. `0.25` means 25% commission.
`ongoing_rate`	`decimal`	Commission rate (0 to 1) applied to a referred user's transactions after the initial period.
`initial_rate_period_days`	`integer`	Length, in days, of the initial commission period. After this many days from a user's first transaction, `ongoing_rate` is applied instead of `initial_rate`.
`max_earnings_per_referred`	`decimal`	Maximum USD commission that can be earned from a single referred user across the lifetime of the channel.
`created_at`	`datetime`	Timestamp of when the channel was created.

In JSON format

referral_channel.json

{
  "id": 1,
  "code": "SUMMER20",
  "description": "20% off the first purchase",
  "promo_type": "percent_off",
  "promo_value": "0.20",
  "is_active": true,
  "is_recurring": false,
  "start_date": "2026-01-01T00:00:00-08:00",
  "end_date": null,
  "total_uses": 42,
  "total_commission": 128.50,
  "total_revenue": 612.40,
  "initial_rate": "0.25",
  "ongoing_rate": "0.10",
  "initial_rate_period_days": 30,
  "max_earnings_per_referred": "1000.00",
  "created_at": "2025-12-15T11:58:10.246406-08:00"
}

List referral channels

Returns the referral channels owned by the authenticated user. The response is an array ordered by id ascending; the endpoint is not paginated.

Request & Response

GET https://proxy.webshare.io/api/v2/referral/channel/

list_referral_channels.py

import requests
 
response = requests.get(
    "https://proxy.webshare.io/api/v2/referral/channel/",
    headers={"Authorization": "Token APIKEY"}
)
 
response.json()

The commands above return JSON structured like this:

response.json

[
  {
    "id": 1,
    "code": "SUMMER20",
    "description": "20% off the first purchase",
    "promo_type": "percent_off",
    "promo_value": "0.20",
    "is_active": true,
    "is_recurring": false,
    "start_date": "2026-01-01T00:00:00-08:00",
    "end_date": null,
    "total_uses": 42,
    "total_commission": 128.50,
    "total_revenue": 612.40,
    "initial_rate": "0.25",
    "ongoing_rate": "0.10",
    "initial_rate_period_days": 30,
    "max_earnings_per_referred": "1000.00",
    "created_at": "2025-12-15T11:58:10.246406-08:00"
  }
]

Earn out Coupon Code