> ## Documentation Index
> Fetch the complete documentation index at: https://autumn-b9b4c0fb-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Referral Program

> Create a referral program linked to an existing reward.

### Body Parameters

<DynamicParamField body="id" type="string" required />

<DynamicParamField body="reward_id" type="string" required />

<DynamicParamField body="redeem_on" type="'customer_creation' | 'checkout'" required>
  When the reward is granted: on redemption, or when the redeemer checks out.
</DynamicParamField>

<DynamicParamField body="received_by" type="'referrer' | 'all'" required>
  Who receives the reward: the referrer only, or both parties.
</DynamicParamField>

<DynamicParamField body="max_redemptions" type="integer | null">
  A positive redemption limit, or null for unlimited redemptions.
</DynamicParamField>

<DynamicParamField body="plan_ids" type="string[] | null">
  Required when redeem\_on is checkout. Plan IDs must be unique.
</DynamicParamField>

<DynamicParamField body="exclude_trial" type="boolean | null">
  Whether checkouts that start a trial should skip granting the reward.
</DynamicParamField>

<DynamicParamField body="internal_id" type="string">
  Address an existing referral program by its stable id. Omit when creating — the server generates one.
</DynamicParamField>

### Response

<DynamicResponseField name="id" type="string">
  The unique identifier for the referral program.
</DynamicResponseField>

<DynamicResponseField name="reward_id" type="string">
  The ID of the reward granted when a code is redeemed.
</DynamicResponseField>

<DynamicResponseField name="redeem_on" type="'customer_creation' | 'checkout'">
  When the reward is granted: on redemption, or when the redeemer checks out.
</DynamicResponseField>

<DynamicResponseField name="received_by" type="'referrer' | 'all'">
  Who receives the reward: the referrer only, or both parties.
</DynamicResponseField>

<DynamicResponseField name="max_redemptions" type="number | null">
  The maximum number of times a referral code can be redeemed.
</DynamicResponseField>

<DynamicResponseField name="plan_ids" type="string[] | null">
  The plans whose checkout triggers the reward. Only used when redeem\_on is checkout.
</DynamicResponseField>

<DynamicResponseField name="exclude_trial" type="boolean | null">
  Whether checkouts that start a trial should skip granting the reward.
</DynamicResponseField>

<DynamicResponseField name="created_at" type="number">
  The Unix timestamp (in milliseconds) when the referral program was created.
</DynamicResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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
  }
  ```
</ResponseExample>


## OpenAPI

````yaml openapi POST /v1/referral_programs.create
openapi: 3.1.0
info:
  title: Autumn API
  version: 2.4.0
servers:
  - url: https://api.useautumn.com
    description: Production server
security:
  - secretKey: []
paths:
  /v1/referral_programs.create:
    post:
      tags:
        - referrals
      description: Create a referral program linked to an existing reward.
      operationId: createReferralProgram
      parameters:
        - name: x-api-version
          in: header
          required: true
          schema:
            type: string
            default: 2.4.0
          x-speakeasy-globals-hidden: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  minLength: 1
                reward_id:
                  type: string
                  minLength: 1
                redeem_on:
                  enum:
                    - customer_creation
                    - checkout
                  type: string
                  description: >-
                    When the reward is granted: on redemption, or when the
                    redeemer checks out.
                received_by:
                  enum:
                    - referrer
                    - all
                  type: string
                  description: 'Who receives the reward: the referrer only, or both parties.'
                max_redemptions:
                  anyOf:
                    - type: integer
                      minimum: -9007199254740991
                      maximum: 9007199254740991
                      exclusiveMinimum: 0
                    - type: 'null'
                  description: >-
                    A positive redemption limit, or null for unlimited
                    redemptions.
                plan_ids:
                  anyOf:
                    - type: array
                      items:
                        type: string
                        minLength: 1
                    - type: 'null'
                  description: >-
                    Required when redeem_on is checkout. Plan IDs must be
                    unique.
                exclude_trial:
                  anyOf:
                    - type: boolean
                    - type: 'null'
                  description: >-
                    Whether checkouts that start a trial should skip granting
                    the reward.
                internal_id:
                  type: string
                  minLength: 1
                  description: >-
                    Address an existing referral program by its stable id. Omit
                    when creating — the server generates one.
              required:
                - id
                - reward_id
                - redeem_on
                - received_by
              additionalProperties: false
              title: CreateReferralProgramParams
              examples:
                - 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
            example:
              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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The unique identifier for the referral program.
                  reward_id:
                    type: string
                    description: The ID of the reward granted when a code is redeemed.
                  redeem_on:
                    enum:
                      - customer_creation
                      - checkout
                    type: string
                    description: >-
                      When the reward is granted: on redemption, or when the
                      redeemer checks out.
                  received_by:
                    enum:
                      - referrer
                      - all
                    type: string
                    description: >-
                      Who receives the reward: the referrer only, or both
                      parties.
                  max_redemptions:
                    anyOf:
                      - type: number
                      - type: 'null'
                    description: >-
                      The maximum number of times a referral code can be
                      redeemed.
                  plan_ids:
                    anyOf:
                      - type: array
                        items:
                          type: string
                      - type: 'null'
                    description: >-
                      The plans whose checkout triggers the reward. Only used
                      when redeem_on is checkout.
                  exclude_trial:
                    anyOf:
                      - type: boolean
                      - type: 'null'
                    description: >-
                      Whether checkouts that start a trial should skip granting
                      the reward.
                  created_at:
                    type: number
                    description: >-
                      The Unix timestamp (in milliseconds) when the referral
                      program was created.
                required:
                  - id
                  - reward_id
                  - redeem_on
                  - received_by
                  - created_at
                title: CreateReferralProgramResponse
                examples:
                  - 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
              example:
                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
      x-codeSamples:
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            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,
            });
        - lang: python
          label: Python (SDK)
          source: |-
            from autumn_sdk import Autumn

            autumn = Autumn(secret_key="am_sk_test...")

            res = autumn.referrals.create_program(
                id="refer_a_friend",
                reward_id="beta_credits_grant",
                redeem_on="customer_creation",
                received_by="referrer",
                max_redemptions=10,
                plan_ids=None,
                exclude_trial=False,
            )
components:
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````