Create Referral Program

Create a referral program linked to an existing reward.

POST /v1/referral_programs.create

Typescript (SDK)

TypeScript

import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.referrals.createProgram({
  id: "refer_a_friend",
  rewardId: "beta_credits_grant",
  redeemOn: "customer_creation",
  receivedBy: "referrer",
  maxRedemptions: 10,
  planIds: null,
  excludeTrial: false,
});

200

{
  "id": "refer_a_friend",
  "reward_id": "beta_credits_grant",
  "redeem_on": "customer_creation",
  "received_by": "referrer",
  "max_redemptions": 10,
  "plan_ids": null,
  "exclude_trial": false,
  "created_at": 1718000000000
}

Body Parameters

Response

200

{
  "id": "refer_a_friend",
  "reward_id": "beta_credits_grant",
  "redeem_on": "customer_creation",
  "received_by": "referrer",
  "max_redemptions": 10,
  "plan_ids": null,
  "exclude_trial": false,
  "created_at": 1718000000000
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-api-version · string · default: 2.4.0 · required

Body

application/json

id · string · required

Minimum string length: 1

reward_id · string · required

Minimum string length: 1

redeem_on · enum<string> · required

When the reward is granted: on redemption, or when the redeemer checks out.

Available options: customer_creation, checkout

received_by · enum<string> · required

Who receives the reward: the referrer only, or both parties.

Available options: referrer, all

max_redemptions · integer | null

A positive redemption limit, or null for unlimited redemptions.

Required range: 0 < x <= 9007199254740991

plan_ids · string[] | null

Required when redeem_on is checkout. Plan IDs must be unique.

Minimum string length: 1

exclude_trial · boolean | null

Whether checkouts that start a trial should skip granting the reward.

internal_id · string

Address an existing referral program by its stable id. Omit when creating — the server generates one.

Minimum string length: 1

Response

200 - application/json

OK

id · string · required

The unique identifier for the referral program.

reward_id · string · required

The ID of the reward granted when a code is redeemed.

redeem_on · enum<string> · required

When the reward is granted: on redemption, or when the redeemer checks out.

Available options: customer_creation, checkout

received_by · enum<string> · required

Who receives the reward: the referrer only, or both parties.

Available options: referrer, all

created_at · number · required

The Unix timestamp (in milliseconds) when the referral program was created.

max_redemptions · number | null

The maximum number of times a referral code can be redeemed.

plan_ids · string[] | null

The plans whose checkout triggers the reward. Only used when redeem_on is checkout.

exclude_trial · boolean | null

Whether checkouts that start a trial should skip granting the reward.