Storefront APIs

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

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

// 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

// 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