Loyalty & Referrals

These docs are moving to docs.yotpo.com on November 5. Your links will keep working and take you to the same page on the new site.

Quickstart

Look up a customer's points in one call

Send your GUID and API key in headers from your server. You get the customer's balance, VIP tier and when their points expire.

Try it in the reference Find your GUID and API key

cURLServer-side only

# Fetch a customer's points and tier
curl "https://loyalty.yotpo.com/api/v2/customers?customer_email=[email protected]" \
  -H "X-GUID: YOUR_GUID" \
  -H "X-API-KEY: YOUR_API_KEY"

Example response

{
  "email": "[email protected]",
  "points_balance": 250,
  "points_earned": 250,
  "vip_tier_name": "Silver",
  "points_expire_at": "2028-10-24T00:00:00.000+00:00",
  ...
}

Build by use case

See all use cases

Guide Integrate a custom or headless store Customers, orders, refunds, rewards and points in your own UI, all from your server. Recipe Award points for orders Record an order and watch the points land against your active campaigns. Recipe Redeem points for rewards List the rewards a customer can afford, redeem one and hand over the code. Recipe Reward custom actions Give points for surveys, app installs and anything outside a purchase. Recipe Run a referral flow Register a referrer, get their link and send invitations to friends. Use case Show points on product pages Display "Earn 30 points" with your earning rules and VIP multipliers.

More Yotpo APIs

Core Orders, products, customers, collections and webhooks for every Yotpo product. core-api.yotpo.com Reviews & UGC Reviews, ratings, Q&A and visual content for any storefront or backend. apidocs.yotpo.com App partners Build an app on Yotpo and become a technology partner. develop.yotpo.com

Essentials

Authentication Your GUID and API key, sent in headers. Which endpoints use other credentials. Errors Every status code, the error bodies, and which calls are safe to retry. Testing your integration Which calls change points, send emails or create coupons, and how to test safely. Guidelines & conventions Rate limits, errors and testing at a glance. Changelog The latest changes to the Loyalty API and its docs. llms.txt for AI tools Every page and endpoint in one file for Cursor, Claude and other assistants.