---
title: "Accept referral offer (POST)"
method: POST
path: "/loyalty/cp/api/referral-rules/accept-offer"
tags: ["Referrals"]
---

# Accept referral offer (POST)

`POST /loyalty/cp/api/referral-rules/accept-offer`

## Request

- Base URL: `https://your-store.myshopify.com/apps`
- URL: `https://your-store.myshopify.com/apps/loyalty/cp/api/referral-rules/accept-offer`
- Auth: none declared

Accepts a referral offer when a new customer uses a referral link.

**Referral flow overview:**
1. Existing customer (referrer) shares referral link
2. New customer (referee) clicks link
3. Link contains unique token
4. New customer signs up or browses
5. Call this endpoint with token and email
6. System creates referral record
7. May generate welcome discount for referee
8. Referrer gets points when referee makes purchase

**Request body:**
- token: Unique referral token from URL (required)
- email: New customer's email address (required)

**What this endpoint does:**
1. Validates referral token is valid
2. Checks referral program is active
3. Verifies referee hasn't used a referral before
4. Creates referral record linking referee to referrer
5. Generates welcome discount code (if configured)
6. May award immediate points to referee
7. Tracks referral for future reward distribution
8. Returns discount code for referee to use

**Referral rewards configuration:**
Different merchants configure different rewards:
- Referee discount: Welcome discount for new customer
- Referrer points: Points when referee makes purchase
- Both rewards: Both parties get something
- Tiered rewards: More for higher-value purchases

**Token validation:**
- Token must exist in system
- Token must belong to active customer
- Customer must have referral program enabled
- Token has no expiration (typically)
- Each token is unique per customer

**Duplicate prevention:**
- Email can only accept one referral
- Cannot accept own referral
- Cannot accept multiple referrals
- First referral link used is the one that counts

**Response includes:**
- id: Referral record ID
- message: Success or error message
- discountCode: Welcome discount for referee (if applicable)
- status: SUCCESS or ERROR

**Integration points:**

**Option 1: Signup page integration**
```javascript
// During signup process
const urlParams = new URLSearchParams(window.location.search);
const referralToken = urlParams.get('token');
if (referralToken) {
  // After customer enters email
  await acceptReferral(referralToken, customerEmail);
  // Show welcome discount to customer
}
```

**Option 2: Landing page integration**
```javascript
// On referral landing page
const token = getReferralToken();
document.getElementById('claimButton').onclick = async () => {
  const email = document.getElementById('email').value;
  const response = await acceptReferral(token, email);
  showDiscountCode(response.discountCode);
};
```

**Referral tracking states:**
- PENDING: Referral accepted, waiting for first purchase
- COMPLETED: Referee made qualifying purchase, rewards distributed
- EXPIRED: Referral expired before qualifying purchase

**Best practices:**
1. Call this endpoint early in customer journey
2. Store referral token in cookie/session if email not available yet
3. Show welcome discount prominently after acceptance
4. Explain referral benefits clearly
5. Handle already-accepted gracefully
6. Track conversion rate of referrals
7. A/B test referral incentives

**Common error scenarios:**
- Invalid token: Token doesn't exist or is malformed
- Referral program inactive: Store disabled referrals
- Already accepted: This email already used a referral
- Self-referral: Customer trying to refer themselves
- Token from excluded customer: Referrer is excluded from program

**When rewards are distributed:**
- Referee: Welcome discount immediately on acceptance
- Referrer: Points awarded when referee makes first purchase
- Both: May get additional rewards for repeat purchases

## Request body

- ReferralAcceptRequest: Referral acceptance request containing referral token and email address of the new customer
  - `email` string
  - `token` string

## Response `201`

Referral offer accepted successfully

- ReferralAcceptResponse
  - `discountCode` string
  - `errorKey` string
  - `existingCustomer` boolean
  - `id` integer
  - `message` string
  - `status` 'SUCCESS' | 'FAILED'

## Other responses

- `400`: Invalid token or email, referral already accepted, or referral program not available

## Changes

- **2026-10-06** `eace591c6962`: 2 info
  - added the optional property `existingCustomer` to the response with the `201` status
  - added the optional property `existingCustomer` to the response with the `400` status
- **2026-09-05** `0f423f0dce11`: 2 info
  - added the optional property `errorKey` to the response with the `201` status
  - added the optional property `errorKey` to the response with the `400` status

[Operation history](https://skmtc.dev/appstle/apis/storefront-apis/changes/loyalty/cp/api/referral-rules/accept-offer/post.md)

---

[API](https://skmtc.dev/appstle/apis/storefront-apis.md) - [All operations](https://skmtc.dev/appstle/apis/storefront-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/appstle/apis/storefront-apis/revisions/9f59d178ff71?raw)