---
title: "Update a referral"
method: PUT
path: "/referrals"
---

# Update a referral

`PUT /referrals`

Updates a referral identified by `referralId`, and fires the `referral.updated` webhook.

Use `subscriptionStatus` to change whether a referral counts as active. Any field you send is applied directly to the referral, so sending a field that is not listed below will fail the request.

## Request body

- ReferralUpdate
  - `referralId` string, uuid, required — The referral to update
  - `name` string — Name of the referred user
  - `email` string, email — Email of the referred user. Lowercased before saving.
  - `referredUserExternalId` string — The ID you maintain for this user in your own system.
  - `plan` string — Plan the referred user is on
  - `subscriptionStatus` 'ACTIVE' | 'SUBMITTED' | 'DECLINED' — Status of the referral
  - `notes` string — Free-text notes on the referral
  - `metadata` object — Arbitrary JSON to attach to the referral

## Response `200`

The updated referral.

- Referral
  - `id` string, uuid — The referral ID
  - `affiliateId` string, uuid, nullable — The affiliate credited with this referral
  - `affiliateProgramId` string, uuid, nullable — The affiliate program this referral belongs to
  - `affiliateLinkId` string, uuid, nullable — The affiliate link the referral came through
  - `commissionPlanId` string, uuid, nullable — The commission plan applied to this referral
  - `name` string, nullable — Name of the referred user
  - `email` string, email, nullable — Email of the referred user
  - `referredUserExternalId` string — The ID you maintain for this user in your own system — for example your database user ID or a Stripe customer ID.
  - `plan` string, nullable — Plan the referred user is on. Defaults to `N/A` when not supplied.
  - `subscriptionStatus` 'ACTIVE' | 'SUBMITTED' | 'DECLINED', nullable — Status of the referral. Referrals created through this API are always `ACTIVE`.
  - `submissionType` 'MANUAL' | 'AUTOMATIC', nullable — Whether the referral was submitted by hand or captured automatically
  - `referralMedium` 'COUPON' | 'LINK', nullable — How the referral was tracked
  - `source` 'UNKNOWN' | 'API' | 'INTEGRATION' | 'MANUAL' | 'IMPORTED' | 'AFFILIATE_SUBMITTED' — Where the referral came from. Referrals created through this API have `API`.
  - `totalRevenue` number, float — Total revenue attributed to this referral
  - `totalCommission` number, float — Total commission generated by this referral
  - `initialLandingPage` string, nullable — The first page the referred user landed on
  - `notes` string, nullable — Free-text notes on the referral
  - `metadata` object, nullable — Arbitrary JSON you can attach to the referral
  - `createdAt` string, date-time — When the referral was created

## Other responses

- `400` — `referralId` was missing, no referral in this program has that ID, or the request contained a field that cannot be updated.
- `401` — The `Authorization` header is missing, is not a `Bearer` header, or the token is not valid.
- `403` — API access is not enabled for this account.
- `404` — The affiliate program this token belongs to no longer exists.
- `429` — Too many requests for this token on this endpoint. Please slow down.

---

[API](https://skmtc.net/referly/apis/referly-api.md) · [All operations](https://skmtc.net/referly/apis/referly-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/referly/referly-api/revisions/0f506d61b9c3/schema)