Referrals API

REST endpoints for referrals in SKUFlow: 13 operations with parameters, request and response fields, permissions and curl examples.

Base URL: https://app.skuflow.ai/api. Every call needs Authorization: Bearer skf_… (Authentication); {organizationId} ($ORGANIZATION_ID in the examples) is your business's id.

Operation	Endpoint	Risk
Get the referral programme	`GET /organizations/{organizationId}/marketing/referrals/program`	`read`
Change the referral programme	`PATCH /organizations/{organizationId}/marketing/referrals/program`	`write`
List referrals	`GET /organizations/{organizationId}/marketing/referrals`	`read`
Record a referral	`POST /organizations/{organizationId}/marketing/referrals`	`write`
Referrals report	`GET /organizations/{organizationId}/marketing/referrals/report`	`read`
Get a referral	`GET /organizations/{organizationId}/marketing/referrals/{referralId}`	`read`
Link a referral to its customer	`POST /organizations/{organizationId}/marketing/referrals/{referralId}/link`	`write`
Reject a referral	`POST /organizations/{organizationId}/marketing/referrals/{referralId}/reject`	`write`
Check referral conversions now	`POST /organizations/{organizationId}/marketing/referrals/check`	`write`
List referral rewards	`GET /organizations/{organizationId}/marketing/referrals/rewards`	`read`
Use a referral reward	`POST /organizations/{organizationId}/marketing/referrals/rewards/{rewardId}/apply`	`sensitive`
Void a referral reward	`POST /organizations/{organizationId}/marketing/referrals/rewards/{rewardId}/void`	`sensitive`
A customer's referral link	`GET /organizations/{organizationId}/customers/{customerId}/referral`	`read`

Get the referral programme

GET /organizations/{organizationId}/marketing/referrals/program

On/off, the rewards for the referrer and the new customer, the terms, what counts as a conversion and the cap per referrer. Read-only.


Permission	`marketing.read` (Owner, Admin, Staff)
Risk	`read`, OAuth scope `skuflow.read`. Read: reads only.
MCP tool	`referrals_program` (toolset `marketing`)

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/marketing/referrals/program" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`enabled`	boolean
`referrerRewardKind`	enum	One of `ACCOUNT_CREDIT`, `DISCOUNT`, `GIFT_CARD`, `NONE`.
`referrerRewardCents`	integer
`referrerRewardNote`	string or null
`friendRewardKind`	enum	One of `ACCOUNT_CREDIT`, `DISCOUNT`, `GIFT_CARD`, `NONE`.
`friendRewardCents`	integer
`friendRewardNote`	string or null
`headline`	string or null
`terms`	string or null
`conversion`	enum	One of `FIRST_PAID_INVOICE`.
`rewardCap`	integer or null
`rewardCapPeriodDays`	integer
`updatedAt`	string (date-time) or null

Change the referral programme

PATCH /organizations/{organizationId}/marketing/referrals/program

Changes the fields sent. Turning it on gives every customer a link (/ref/{code}, the {{links.referral}} merge field, the portal) and turns on the "Referral reward thank-you" automation the first time.


Permission	`marketing.manage` (Owner, Admin)
Risk	`write`, OAuth scope `skuflow.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`referrals_updateProgram` (toolset `marketing`)
Plan	Marketing campaigns: the Grow plan and up.

Request body

Field	Type	Required	Description
`enabled`	boolean	No	On: customers get a link and rewards are issued.
`referrerRewardKind`	enum	No	What the customer who referred gets: ACCOUNT_CREDIT (a credit line on an invoice), DISCOUNT, GIFT_CARD (sent by hand) or NONE. One of `ACCOUNT_CREDIT`, `DISCOUNT`, `GIFT_CARD`, `NONE`.
`referrerRewardCents`	integer	No	0–1000000.
`referrerRewardNote`	string or null	No	e.g. "$50 Amazon gift card". Up to 200 characters.
`friendRewardKind`	enum	No	What the new customer gets on their first invoice. One of `ACCOUNT_CREDIT`, `DISCOUNT`, `GIFT_CARD`, `NONE`.
`friendRewardCents`	integer	No	0–1000000.
`friendRewardNote`	string or null	No	Up to 200 characters.
`headline`	string or null	No	The landing page's headline. Up to 120 characters.
`terms`	string or null	No	Up to 4000 characters.
`conversion`	enum	No	When a referral counts: the first paid invoice. One of `FIRST_PAID_INVOICE`.
`rewardCap`	integer or null	No	At most this many rewarded referrals per referrer per period; null = no cap. 1–1000.
`rewardCapPeriodDays`	integer	No	1–3650.

Example

curl -X PATCH "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/marketing/referrals/program" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"referrerRewardKind":"ACCOUNT_CREDIT","referrerRewardCents":12500}'

Response

200: the answer's fields

Field	Type	Description
`enabled`	boolean
`referrerRewardKind`	enum	One of `ACCOUNT_CREDIT`, `DISCOUNT`, `GIFT_CARD`, `NONE`.
`referrerRewardCents`	integer
`referrerRewardNote`	string or null
`friendRewardKind`	enum	One of `ACCOUNT_CREDIT`, `DISCOUNT`, `GIFT_CARD`, `NONE`.
`friendRewardCents`	integer
`friendRewardNote`	string or null
`headline`	string or null
`terms`	string or null
`conversion`	enum	One of `FIRST_PAID_INVOICE`.
`rewardCap`	integer or null
`rewardCapPeriodDays`	integer
`updatedAt`	string (date-time) or null

List referrals

GET /organizations/{organizationId}/marketing/referrals

Who referred whom, newest first: status (PENDING, CONVERTED, REJECTED with the reason), the request it came in as, and the rewards. Read-only.


Permission	`marketing.read` (Owner, Admin, Staff)
Risk	`read`, OAuth scope `skuflow.read`. Read: reads only.
MCP tool	`referrals_list` (toolset `marketing`)

Parameters

Name	In	Type	Required	Description
`status`	query	enum	No	One of `PENDING`, `CONVERTED`, `REJECTED`.
`referrerCustomerId`	query	string	No
`limit`	query	integer	No	1–200.
`offset`	query	integer	No

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/marketing/referrals" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`total`	integer
`items`	array of object
`items[].id`	string
`items[].status`	enum	One of `PENDING`, `CONVERTED`, `REJECTED`.
`items[].source`	string
`items[].rejectReason`	string or null	SELF_REFERRAL, EXISTING_CUSTOMER, DUPLICATE or STAFF.
`items[].code`	string or null
`items[].referrer`	object
`items[].referrer.id`	string
`items[].referrer.name`	string
`items[].referred`	object or null
`items[].referred.id`	string
`items[].referred.name`	string
`items[].friendName`	string or null
`items[].friendEmail`	string or null
`items[].friendPhone`	string or null
`items[].request`	object or null
`items[].request.id`	string
`items[].request.identifier`	string
`items[].request.status`	string
`items[].convertedAt`	string (date-time) or null
`items[].rewardWithheld`	boolean	Converted, but the referrer had reached the cap.
`items[].createdAt`	string (date-time)
`items[].rewards`	array of object
`items[].rewards[].id`	string
`items[].rewards[].referralId`	string
`items[].rewards[].customerId`	string
`items[].rewards[].party`	enum	One of `REFERRER`, `FRIEND`.
`items[].rewards[].kind`	enum	One of `ACCOUNT_CREDIT`, `DISCOUNT`, `GIFT_CARD`, `NONE`.
`items[].rewards[].amountCents`	integer
`items[].rewards[].note`	string or null
`items[].rewards[].status`	enum	One of `ISSUED`, `APPLIED`, `VOID`.
`items[].rewards[].invoiceId`	string or null
`items[].rewards[].issuedAt`	string (date-time)
`items[].rewards[].appliedAt`	string (date-time) or null
`items[].rewards[].voidedAt`	string (date-time) or null
`items[].rewards[].description`	string

Record a referral

POST /organizations/{organizationId}/marketing/referrals

Staff record that one customer referred another ("referred by"). Refused for the same person or one sharing their email, phone or address (400) and for a customer already referred (409). Someone who already paid the business is recorded as REJECTED (existing customer); otherwise the new customer's reward is issued.


Permission	`marketing.manage` (Owner, Admin)
Risk	`write`, OAuth scope `skuflow.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`referrals_create` (toolset `marketing`)
Plan	Marketing campaigns: the Grow plan and up.

Request body

Field	Type	Required	Description
`referrerCustomerId`	string	Yes	The customer who referred.
`referredCustomerId`	string	Yes	The new customer.

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/marketing/referrals" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"referrerCustomerId":"referrerCustomer_id","referredCustomerId":"referredCustomer_id"}'

Response

201: the answer's fields

Field	Type	Description
`id`	string
`status`	enum	One of `PENDING`, `CONVERTED`, `REJECTED`.
`source`	string
`rejectReason`	string or null	SELF_REFERRAL, EXISTING_CUSTOMER, DUPLICATE or STAFF.
`code`	string or null
`referrer`	object
`referrer.id`	string
`referrer.name`	string
`referred`	object or null
`referred.id`	string
`referred.name`	string
`friendName`	string or null
`friendEmail`	string or null
`friendPhone`	string or null
`request`	object or null
`request.id`	string
`request.identifier`	string
`request.status`	string
`convertedAt`	string (date-time) or null
`rewardWithheld`	boolean	Converted, but the referrer had reached the cap.
`createdAt`	string (date-time)
`rewards`	array of object
`rewards[].id`	string
`rewards[].referralId`	string
`rewards[].customerId`	string
`rewards[].party`	enum	One of `REFERRER`, `FRIEND`.
`rewards[].kind`	enum	One of `ACCOUNT_CREDIT`, `DISCOUNT`, `GIFT_CARD`, `NONE`.
`rewards[].amountCents`	integer
`rewards[].note`	string or null
`rewards[].status`	enum	One of `ISSUED`, `APPLIED`, `VOID`.
`rewards[].invoiceId`	string or null
`rewards[].issuedAt`	string (date-time)
`rewards[].appliedAt`	string (date-time) or null
`rewards[].voidedAt`	string (date-time) or null
`rewards[].description`	string

Referrals report

GET /organizations/{organizationId}/marketing/referrals/report

Referrals, conversions and the conversion rate, rewards issued / applied / outstanding, and the top referrers, over the last days (default: all time). Read-only.


Permission	`marketing.read` (Owner, Admin, Staff)
Risk	`read`, OAuth scope `skuflow.read`. Read: reads only.
MCP tool	`referrals_report` (toolset `marketing`)

Parameters

Name	In	Type	Required	Description
`days`	query	integer	No	1–3650.

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/marketing/referrals/report" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`total`	integer
`pending`	integer
`converted`	integer
`rejected`	integer
`conversionRate`	number
`rewards`	object
`rewards.issuedCents`	integer
`rewards.appliedCents`	integer
`rewards.outstandingCents`	integer
`rewards.count`	integer
`topReferrers`	array of object
`topReferrers[].customerId`	string
`topReferrers[].name`	string
`topReferrers[].referrals`	integer
`topReferrers[].converted`	integer

Get a referral

GET /organizations/{organizationId}/marketing/referrals/{referralId}

One referral with its rewards. Read-only.


Permission	`marketing.read` (Owner, Admin, Staff)
Risk	`read`, OAuth scope `skuflow.read`. Read: reads only.
MCP tool	`referrals_get` (toolset `marketing`)

Parameters

Name	In	Type	Required	Description
`referralId`	path	string	Yes	A referral id, from GET /marketing/referrals.

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/marketing/referrals/{referralId}" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`id`	string
`status`	enum	One of `PENDING`, `CONVERTED`, `REJECTED`.
`source`	string
`rejectReason`	string or null	SELF_REFERRAL, EXISTING_CUSTOMER, DUPLICATE or STAFF.
`code`	string or null
`referrer`	object
`referrer.id`	string
`referrer.name`	string
`referred`	object or null
`referred.id`	string
`referred.name`	string
`friendName`	string or null
`friendEmail`	string or null
`friendPhone`	string or null
`request`	object or null
`request.id`	string
`request.identifier`	string
`request.status`	string
`convertedAt`	string (date-time) or null
`rewardWithheld`	boolean	Converted, but the referrer had reached the cap.
`createdAt`	string (date-time)
`rewards`	array of object
`rewards[].id`	string
`rewards[].referralId`	string
`rewards[].customerId`	string
`rewards[].party`	enum	One of `REFERRER`, `FRIEND`.
`rewards[].kind`	enum	One of `ACCOUNT_CREDIT`, `DISCOUNT`, `GIFT_CARD`, `NONE`.
`rewards[].amountCents`	integer
`rewards[].note`	string or null
`rewards[].status`	enum	One of `ISSUED`, `APPLIED`, `VOID`.
`rewards[].invoiceId`	string or null
`rewards[].issuedAt`	string (date-time)
`rewards[].appliedAt`	string (date-time) or null
`rewards[].voidedAt`	string (date-time) or null
`rewards[].description`	string

Link a referral to its customer

POST /organizations/{organizationId}/marketing/referrals/{referralId}/link

For a pending referral whose request was handled by hand: the customer it became. The fraud guards run again; the new customer's reward is issued.


Permission	`marketing.manage` (Owner, Admin)
Risk	`write`, OAuth scope `skuflow.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`referrals_link` (toolset `marketing`)
Plan	Marketing campaigns: the Grow plan and up.

Parameters

Name	In	Type	Required	Description
`referralId`	path	string	Yes	A referral id, from GET /marketing/referrals.

Request body

Field	Type	Required	Description
`customerId`	string	Yes

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/marketing/referrals/{referralId}/link" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customerId":"customer_id"}'

Response

200: the answer's fields

Field	Type	Description
`id`	string
`status`	enum	One of `PENDING`, `CONVERTED`, `REJECTED`.
`source`	string
`rejectReason`	string or null	SELF_REFERRAL, EXISTING_CUSTOMER, DUPLICATE or STAFF.
`code`	string or null
`referrer`	object
`referrer.id`	string
`referrer.name`	string
`referred`	object or null
`referred.id`	string
`referred.name`	string
`friendName`	string or null
`friendEmail`	string or null
`friendPhone`	string or null
`request`	object or null
`request.id`	string
`request.identifier`	string
`request.status`	string
`convertedAt`	string (date-time) or null
`rewardWithheld`	boolean	Converted, but the referrer had reached the cap.
`createdAt`	string (date-time)
`rewards`	array of object
`rewards[].id`	string
`rewards[].referralId`	string
`rewards[].customerId`	string
`rewards[].party`	enum	One of `REFERRER`, `FRIEND`.
`rewards[].kind`	enum	One of `ACCOUNT_CREDIT`, `DISCOUNT`, `GIFT_CARD`, `NONE`.
`rewards[].amountCents`	integer
`rewards[].note`	string or null
`rewards[].status`	enum	One of `ISSUED`, `APPLIED`, `VOID`.
`rewards[].invoiceId`	string or null
`rewards[].issuedAt`	string (date-time)
`rewards[].appliedAt`	string (date-time) or null
`rewards[].voidedAt`	string (date-time) or null
`rewards[].description`	string

Reject a referral

POST /organizations/{organizationId}/marketing/referrals/{referralId}/reject

A pending referral earns nothing; the new customer's unused reward is voided.


Permission	`marketing.manage` (Owner, Admin)
Risk	`write`, OAuth scope `skuflow.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`referrals_reject` (toolset `marketing`)

Parameters

Name	In	Type	Required	Description
`referralId`	path	string	Yes	A referral id, from GET /marketing/referrals.

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/marketing/referrals/{referralId}/reject" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`id`	string
`status`	enum	One of `PENDING`, `CONVERTED`, `REJECTED`.
`source`	string
`rejectReason`	string or null	SELF_REFERRAL, EXISTING_CUSTOMER, DUPLICATE or STAFF.
`code`	string or null
`referrer`	object
`referrer.id`	string
`referrer.name`	string
`referred`	object or null
`referred.id`	string
`referred.name`	string
`friendName`	string or null
`friendEmail`	string or null
`friendPhone`	string or null
`request`	object or null
`request.id`	string
`request.identifier`	string
`request.status`	string
`convertedAt`	string (date-time) or null
`rewardWithheld`	boolean	Converted, but the referrer had reached the cap.
`createdAt`	string (date-time)
`rewards`	array of object
`rewards[].id`	string
`rewards[].referralId`	string
`rewards[].customerId`	string
`rewards[].party`	enum	One of `REFERRER`, `FRIEND`.
`rewards[].kind`	enum	One of `ACCOUNT_CREDIT`, `DISCOUNT`, `GIFT_CARD`, `NONE`.
`rewards[].amountCents`	integer
`rewards[].note`	string or null
`rewards[].status`	enum	One of `ISSUED`, `APPLIED`, `VOID`.
`rewards[].invoiceId`	string or null
`rewards[].issuedAt`	string (date-time)
`rewards[].appliedAt`	string (date-time) or null
`rewards[].voidedAt`	string (date-time) or null
`rewards[].description`	string

Check referral conversions now

POST /organizations/{organizationId}/marketing/referrals/check

Runs what the engine does every few seconds: links referrals to the customers their requests became and converts the ones whose customer paid their first invoice, issuing rewards once.


Permission	`marketing.manage` (Owner, Admin)
Risk	`write`, OAuth scope `skuflow.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`referrals_check` (toolset `marketing`)
Plan	Marketing campaigns: the Grow plan and up.

Request body

Field	Type	Required	Description
`now`	string (date-time)	No	Tests only: act as of this moment (ISO 8601). Refused when NODE_ENV=production.

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/marketing/referrals/check" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"now":"2026-11-03T15:00:00Z"}'

Response

200: the answer's fields

Field	Type	Description
`linked`	integer
`converted`	integer
`rejected`	integer

List referral rewards

GET /organizations/{organizationId}/marketing/referrals/rewards

Rewards earned (ISSUED), used (APPLIED: a credit line on an invoice, or the gift card sent) and voided, newest first. Read-only.


Permission	`marketing.read` (Owner, Admin, Staff)
Risk	`read`, OAuth scope `skuflow.read`. Read: reads only.
MCP tool	`referrals_rewards` (toolset `marketing`)

Parameters

Name	In	Type	Required	Description
`status`	query	enum	No	One of `ISSUED`, `APPLIED`, `VOID`.
`customerId`	query	string	No

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/marketing/referrals/rewards" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields

An array of objects:

Field	Type	Description
`id`	string
`referralId`	string
`customerId`	string
`party`	enum	One of `REFERRER`, `FRIEND`.
`kind`	enum	One of `ACCOUNT_CREDIT`, `DISCOUNT`, `GIFT_CARD`, `NONE`.
`amountCents`	integer
`note`	string or null
`status`	enum	One of `ISSUED`, `APPLIED`, `VOID`.
`invoiceId`	string or null
`issuedAt`	string (date-time)
`appliedAt`	string (date-time) or null
`voidedAt`	string (date-time) or null
`description`	string
`customerName`	string

Use a referral reward

POST /organizations/{organizationId}/marketing/referrals/rewards/{rewardId}/apply

Money: a credit or discount goes on one of the rewarded customer's DRAFT invoices without payments as a credit line (never more than the invoice), lowering what they owe; a gift card is marked as sent. Applying it again to the same invoice changes nothing; to another, 409.


Permission	`marketing.manage` (Owner, Admin)
Risk	`sensitive`, OAuth scope `skuflow.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`referrals_applyReward` (toolset `marketing`)
Approval	Over MCP, this tool asks for your OK first (in the AI app when it supports it, otherwise in SKUFlow). See Approvals.

Parameters

Name	In	Type	Required	Description
`rewardId`	path	string	Yes	A referral reward id, from GET /marketing/referrals/rewards.

Request body

Field	Type	Required	Description
`invoiceId`	string or null	No

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/marketing/referrals/rewards/{rewardId}/apply" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoiceId":"invoice_id"}'

Response

200: the answer's fields

Field	Type	Description
`id`	string
`referralId`	string
`customerId`	string
`party`	enum	One of `REFERRER`, `FRIEND`.
`kind`	enum	One of `ACCOUNT_CREDIT`, `DISCOUNT`, `GIFT_CARD`, `NONE`.
`amountCents`	integer
`note`	string or null
`status`	enum	One of `ISSUED`, `APPLIED`, `VOID`.
`invoiceId`	string or null
`issuedAt`	string (date-time)
`appliedAt`	string (date-time) or null
`voidedAt`	string (date-time) or null
`description`	string

Void a referral reward

POST /organizations/{organizationId}/marketing/referrals/rewards/{rewardId}/void

An unused reward is cancelled; it can no longer be applied.


Permission	`marketing.manage` (Owner, Admin)
Risk	`sensitive`, OAuth scope `skuflow.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`referrals_voidReward` (toolset `marketing`)
Approval	Over MCP, this tool asks for your OK first (in the AI app when it supports it, otherwise in SKUFlow). See Approvals.

Parameters

Name	In	Type	Required	Description
`rewardId`	path	string	Yes	A referral reward id, from GET /marketing/referrals/rewards.

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/marketing/referrals/rewards/{rewardId}/void" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`id`	string
`referralId`	string
`customerId`	string
`party`	enum	One of `REFERRER`, `FRIEND`.
`kind`	enum	One of `ACCOUNT_CREDIT`, `DISCOUNT`, `GIFT_CARD`, `NONE`.
`amountCents`	integer
`note`	string or null
`status`	enum	One of `ISSUED`, `APPLIED`, `VOID`.
`invoiceId`	string or null
`issuedAt`	string (date-time)
`appliedAt`	string (date-time) or null
`voidedAt`	string (date-time) or null
`description`	string

A customer's referral link

GET /organizations/{organizationId}/customers/{customerId}/referral

The customer's referral code and link (/ref/{code}, made the first time it is asked for), visits, the rewards on offer, the people they referred and their rewards.


Permission	`marketing.read` (Owner, Admin, Staff)
Risk	`read`, OAuth scope `skuflow.read`. Read: reads only.
MCP tool	`referrals_customer` (toolset `marketing`)

Parameters

Name	In	Type	Required	Description
`customerId`	path	string	Yes

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/customers/{customerId}/referral" \
  -H "Authorization: Bearer $SKUFLOW_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`enabled`	boolean
`code`	string
`link`	string
`visits`	integer
`referrerReward`	string
`friendReward`	string
`referrals`	array of object
`referrals[].id`	string
`referrals[].status`	string
`referrals[].name`	string or null
`referrals[].createdAt`	string (date-time)
`referrals[].convertedAt`	string (date-time) or null
`rewards`	array of object
`rewards[].id`	string
`rewards[].referralId`	string
`rewards[].customerId`	string
`rewards[].party`	enum	One of `REFERRER`, `FRIEND`.
`rewards[].kind`	enum	One of `ACCOUNT_CREDIT`, `DISCOUNT`, `GIFT_CARD`, `NONE`.
`rewards[].amountCents`	integer
`rewards[].note`	string or null
`rewards[].status`	enum	One of `ISSUED`, `APPLIED`, `VOID`.
`rewards[].invoiceId`	string or null
`rewards[].issuedAt`	string (date-time)
`rewards[].appliedAt`	string (date-time) or null
`rewards[].voidedAt`	string (date-time) or null
`rewards[].description`	string

Get the referral programmeCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Change the referral programmeCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

List referralsCopy Anchor Link

ParametersCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Record a referralCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Referrals reportCopy Anchor Link

ParametersCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Get a referralCopy Anchor Link

ParametersCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Link a referral to its customerCopy Anchor Link

ParametersCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Reject a referralCopy Anchor Link

ParametersCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Check referral conversions nowCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

List referral rewardsCopy Anchor Link

ParametersCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Use a referral rewardCopy Anchor Link

ParametersCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Void a referral rewardCopy Anchor Link

ParametersCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

A customer's referral linkCopy Anchor Link

ParametersCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

On this page

Get the referral programme

Example

Response

Change the referral programme

Request body

Example

Response

List referrals

Parameters

Example

Response

Record a referral

Request body

Example

Response

Referrals report

Parameters

Example

Response

Get a referral

Parameters

Example

Response

Link a referral to its customer

Parameters

Request body

Example

Response

Reject a referral

Parameters

Example

Response

Check referral conversions now

Request body

Example

Response

List referral rewards

Parameters

Example

Response

Use a referral reward

Parameters

Request body

Example

Response

Void a referral reward

Parameters

Example

Response

A customer's referral link

Parameters

Example

Response