# Yotpo Loyalty & Referrals API > REST APIs for Yotpo Loyalty & Referrals: loyalty customer profiles, orders and refunds that earn points, custom actions, point adjustments, redemptions and coupon codes, referrals, campaigns, VIP tiers, and privacy requests. v2.0 (the default version) covers the whole program. v3.0 adds Reward Instances (issued coupons), the current VIP tiers program, and public Product Potential Points for product pages. Every link below is the Markdown version of a page. Endpoint entries start with the HTTP method and full URL. ## Key facts - **Base URLs.** `https://loyalty.yotpo.com` for all v2.0 endpoints (`/api/v2/...`) and Reward Instances (`/v3/stores/{store_id}/reward_instances`). `https://api.yotpo.com/loyalty` for the v3.0 VIP Tiers API. `https://storefront.yotpo.com/loyalty` for Product Potential Points. - **Authentication.** - v2.0 endpoints: your Loyalty GUID and API key in the `X-GUID` and `X-API-KEY` headers (both in the Loyalty admin settings). Send them only in headers: `guid`/`api_key` query parameters also work but aren't recommended, because URLs end up in logs. - Reward Instances and v3.0 VIP Tiers: a Yotpo access token in the `X-Yotpo-Token` header, created from your store ID (app key) and API secret (see https://core-api.yotpo.com/reference/yotpo-authentication). The Loyalty GUID and API key return `403` there. - Product Potential Points: no credentials. The authenticated variant takes `X-Customer-Email`, `X-Customer-Store-Account-Id` and `X-Customer-Token`, which is the SHA-256 hex digest of the customer's email followed by your Loyalty API key. Build the token on your server. - **Identifying customers.** Most v2.0 endpoints take one of `customer_email`, `customer_id` (your platform's customer ID) or, where listed, `pos_account_id` or `phone_number`. `yotpo_customer_id` is Loyalty's internal ID; the v3.0 VIP Tiers API uses it. - **Asynchronous processing.** Orders and custom actions are processed asynchronously: a `200`/`201` means the request was accepted, not that points were awarded. Check the result with Fetch Customer Details and `with_history=true`. - **Pagination.** Fetch All Recently Updated Customers takes `per_page` and a `page_info` cursor from `metadata.next_page_info`. Reward Instances needs `discount_type` on the first request; for later pages send only `page_info` from `pagination.next_page_info`. - **Errors.** `401` missing or wrong GUID/API key (`{"error": ...}`). Validation errors are `422`, usually with an `errors` object or string naming the problem; `404` unknown customer, order or resource; `429` rate limited. Token-authenticated endpoints return `401` for a bad token and `403` for a missing token or another store's token. The v3.0 VIP Tiers API returns `application/problem+json` errors with a `code`. - **Rate limits.** Limits are set per account. Every response carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `X-RateLimit-Limit-Minute`; back off until `RateLimit-Reset` after a `429`. - **Formats.** JSON bodies with `Content-Type: application/json`. Amounts are in cents (`total_amount_cents`, `price_cents`). - **Not in this API.** Webhook registration and store sync (products, orders, customers) are in the Core API: https://core-api.yotpo.com/llms.txt. Reviews, ratings and visual UGC: https://apidocs.yotpo.com/llms.txt. ## v2.0 · Guides · How-to Guides - [Integrate Loyalty with a custom or headless store](https://loyaltyapi.yotpo.com/docs/custom-generic-implementation.md): Run Yotpo Loyalty & Referrals on a store built on a custom or unsupported platform. Send customers, orders and refunds from your server, set up reward codes, and show points in your own UI. ## v2.0 · Recipes - [Record an order and award points](https://loyaltyapi.yotpo.com/recipes/record-an-order-and-award-points.md): The core loyalty loop: record an order and watch the points land. - [Create a customer record](https://loyaltyapi.yotpo.com/recipes/create-a-customer-record.md): Create a loyalty profile with birthday and anniversary — the foundation for every campaign. - [Refund an order](https://loyaltyapi.yotpo.com/recipes/refund-an-order.md): Record a refund against an order — earned points are adjusted automatically. - [Redeem points for a reward](https://loyaltyapi.yotpo.com/recipes/redeem-points-for-a-reward.md): Fetch the available redemption options, then redeem—the reward code is returned in the response. - [Record a custom action](https://loyaltyapi.yotpo.com/recipes/record-a-custom-action.md): Award points for anything — surveys, reviews, app installs — via custom action campaigns. - [Run a referral flow](https://loyaltyapi.yotpo.com/recipes/run-a-referral-flow.md): Register a referrer and send them referral invitations. ## v2.0 · API reference · General - [Welcome](https://loyaltyapi.yotpo.com/reference/welcome.md): Everything you need before your first Loyalty API call. - [What you can build](https://loyaltyapi.yotpo.com/reference/what-you-can-build.md): Pick what you want to build and follow the path. Each one starts with a recipe or a single call and links to the reference pages you need next. - [Authentication](https://loyaltyapi.yotpo.com/reference/authentication.md): How to authenticate with the Yotpo Loyalty API using your GUID and API key. - [Guidelines & Conventions](https://loyaltyapi.yotpo.com/reference/guidelines-and-conventions.md): Rate limits, errors, testing and usage conventions for the Yotpo Loyalty & Referrals API. - [Errors](https://loyaltyapi.yotpo.com/reference/errors.md): The status codes the Loyalty API returns, the error bodies each part of the API sends, and how to handle each one. - [Testing your integration](https://loyaltyapi.yotpo.com/reference/testing-your-integration.md): There's no sandbox, so every call reaches a real Loyalty program. How to test without changing real customers' points, sending emails or issuing live coupons. ## v2.0 · API reference · Customers - [Create/Update Customer Record](https://loyaltyapi.yotpo.com/reference/createupdate-customer-records.md): `POST https://loyalty.yotpo.com/api/v2/customers` This endpoint both creates and updates a customer’s record in the Yotpo system. Use this primarily to notify Yotpo when you add a customer manually in your admin, or a customer changes their email address. - [Set Customer Birthday](https://loyaltyapi.yotpo.com/reference/set-customer-birthday.md): `POST https://loyalty.yotpo.com/api/v2/customer_birthdays` Stores the customer's birthday, which birthday campaigns use to award points or rewards on the customer's birthday. day and month are required; year is optional. Calling again overwrites the stored birthday. - [Set/Update Customer Anniversary](https://loyaltyapi.yotpo.com/reference/createupdate-customer-anniversary.md): `POST https://loyalty.yotpo.com/api/v2/customer_anniversary` Stores or updates the customer's anniversary date — any date meaningful to your program (signup, first purchase, or a customer-provided date). Used by anniversary campaigns the way birthdays power birthday campaigns. - [Get Customer Anniversary](https://loyaltyapi.yotpo.com/reference/get-customer-anniversary.md): `GET https://loyalty.yotpo.com/api/v2/customer_anniversary` Retrieves the customer's stored anniversary date, if one has been set. Pass an optional `campaign_id` to get the anniversary data as resolved for a specific anniversary campaign. - [Remove Customer Anniversary](https://loyaltyapi.yotpo.com/reference/remove-customer-anniversary.md): `DELETE https://loyalty.yotpo.com/api/v2/customer_anniversary` Deletes the customer's stored anniversary. After removal, the customer no longer triggers anniversary-based campaigns. - [Fetch Customer Details](https://loyaltyapi.yotpo.com/reference/fetch-customer-details.md): `GET https://loyalty.yotpo.com/api/v2/customers` This endpoint returns a customer record. Most commonly used to fetch a customer’s point balance and unique referral link. - [Fetch All Recently Updated Customers](https://loyaltyapi.yotpo.com/reference/fetch-all-recently-updated-customers.md): `GET https://loyalty.yotpo.com/api/v2/customers/recent` Fetches a list of all the customers who were updated in the last 7 days, and their customer data registered in the Yotpo Loyalty database - [Get Customer Tags](https://loyaltyapi.yotpo.com/reference/get-customer-tags.md): `GET https://loyalty.yotpo.com/api/v2/customer_tags` Retrieves the list of tags currently assigned to a customer. - [Add Customer Tags](https://loyaltyapi.yotpo.com/reference/add-customer-tags.md): `PUT https://loyalty.yotpo.com/api/v2/customer_tags/add` Adds one or more tags to a customer. Duplicate tags (case-insensitive) are ignored. - [Remove Customer Tags](https://loyaltyapi.yotpo.com/reference/remove-customer-tags.md): `PUT https://loyalty.yotpo.com/api/v2/customer_tags/remove` Removes one or more tags from a customer. Matching is case-insensitive. ## v2.0 · API reference · Orders - [Create Order](https://loyaltyapi.yotpo.com/reference/create-order.md): `POST https://loyalty.yotpo.com/api/v2/orders` This endpoint records an order made by a customer. It will apply the order to all matching active campaigns and award the necessary points and/or discounts. ## v2.0 · API reference · Refunds - [Create Refund](https://loyaltyapi.yotpo.com/reference/create-refund.md): `POST https://loyalty.yotpo.com/api/v2/refunds` Send a new refund to the Yotpo API to adjust previously processed order. Requests are processed asynchronously. ## v2.0 · API reference · Actions - [Record a Custom Action](https://loyaltyapi.yotpo.com/reference/record-a-customer-action.md): `POST https://loyalty.yotpo.com/api/v2/actions` This endpoint records an action performed by a customer. It will apply the action to all active custom action campaigns and award the necessary points and/or discounts. - [Adjust a Customer's Point Balance](https://loyaltyapi.yotpo.com/reference/adjust-a-customers-point-balance.md): `POST https://loyalty.yotpo.com/api/v2/points/adjust` Adds or removes points from a customer's balance outside of normal campaign earning — for goodwill credits, support resolutions, or corrections. The adjustment appears in the customer's points history. - [Remove a Customer from an Action Based VIP Tier](https://loyaltyapi.yotpo.com/reference/removing-a-customer-from-an-action-based-vip-tier.md): `PUT https://loyalty.yotpo.com/api/v2/actions/cancel_all` Use this endpoint to revoke a customer's action based VIP tier status ## v2.0 · API reference · Point Redemptions - [Create Redemption](https://loyaltyapi.yotpo.com/reference/create-redemption.md): `POST https://loyalty.yotpo.com/api/v2/redemptions` This endpoint will redeem a customer’s points for a particular redemption option. - [Approve Redemption Cancellation](https://loyaltyapi.yotpo.com/reference/approve-redemption-cancellation.md): `POST https://loyalty.yotpo.com/api/v2/redemptions/{point_redemption_id}/cancellation_completed` This endpoint will confirm the Redemption Cancellation Request webhook so that the customer will receive their points from redemption back into their account. ## v2.0 · API reference · Redemption Options - [Upload Coupon Codes](https://loyaltyapi.yotpo.com/reference/add-coupon-codes.md): `POST https://loyalty.yotpo.com/api/v2/redemption_codes` Uploads up to 10,000 coupon codes to a coupon-type redemption option's pool. Codes are handed out one per redemption as customers redeem the option — keep the pool topped up so redemptions never fail for lack of codes. - [Get Active Redemption Options](https://loyaltyapi.yotpo.com/reference/fetch-active-redemption-options.md): `GET https://loyalty.yotpo.com/api/v2/redemption_options` This endpoint returns a list of redemption options available for customers to redeem. - [Get Redemption Code Data](https://loyaltyapi.yotpo.com/reference/get-redemption-code-data.md): `GET https://loyalty.yotpo.com/api/v2/redemption_codes` This endpoint lets you fetch the email address of a customer who redeemed a discount by providing a `third party_id` or the discount `code`. ## v2.0 · API reference · Referrals - [Identify Referrer](https://loyaltyapi.yotpo.com/reference/identify-referrer.md): `POST https://loyalty.yotpo.com/api/v2/referral/referrer` Finds or creates the customer as a referrer and returns their referral link along with their referral history — referral_receipts lists past sign-ups and completed referrals. - [Send Referral Emails](https://loyaltyapi.yotpo.com/reference/send-referral-emails.md): `POST https://loyalty.yotpo.com/api/v2/referral/share` Sends referral invitations to a comma-separated list of addresses on the referrer's behalf. ## v2.0 · API reference · Campaigns - [Get Active Campaigns](https://loyaltyapi.yotpo.com/reference/get-active-campaigns.md): `GET https://loyalty.yotpo.com/api/v2/campaigns` This endpoint returns a list of campaigns available for customers to participate in. If you provide a particular customer we can return their current status and eligibility on each of the campaigns. ## v2.0 · API reference · VIP Tiers - [Fetch VIP Tiers](https://loyaltyapi.yotpo.com/reference/fetch-vip-tiers.md): `GET https://loyalty.yotpo.com/api/v2/vip_tiers` Returns your program's configured VIP tiers, including each tier's ID — use it to display tier structure to customers or to look up the tier IDs other endpoints reference. ## v2.0 · API reference · Privacy - [Data exists](https://loyaltyapi.yotpo.com/reference/data-exists.md): `GET https://loyalty.yotpo.com/api/v2/privacy/data/exists` A synchronous request that checks for existing account data (true/false) in the Yotpo loyalty system. - [User data](https://loyaltyapi.yotpo.com/reference/user-data.md): `GET https://loyalty.yotpo.com/api/v2/privacy/data` An asynchronous request that retrieves existing user data in the Yotpo loyalty system. User data is sent as a JSON file to the account email address associated with the Yotpo loyalty account. - [Anonymize user](https://loyaltyapi.yotpo.com/reference/anonymize-user.md): `DELETE https://loyalty.yotpo.com/api/v2/privacy/data` As part of Global Data Regulation compliance, this endpoint removes and anonymizes end-user personal information collected by Yotpo. To learn more, click here. - [Privacy](https://loyaltyapi.yotpo.com/reference/privacy.md): Check for any existing user data in the Yotpo loyalty system. ## v2.0 · API reference · Webhook Events - [Intro to Webhook Events](https://loyaltyapi.yotpo.com/reference/intro-to-webhook-events.md): Yotpo can publish events to a webhook url or directly to one of our partner integrations. ## v3.0 · API reference · Point Redemptions - [Reward Instances API](https://loyaltyapi.yotpo.com/v3.0/reference/reward-instances-api.md): `GET https://loyalty.yotpo.com/v3/stores/{store_id}/reward_instances` The Reward Instances API allows merchants to retrieve details of coupon-based rewards issued to their customers. This API supports querying reward instances based on discount type, expiration, and usage status. ## v3.0 · API reference · Product Potential Points - [Authenticated Product Potential Points](https://loyaltyapi.yotpo.com/v3.0/reference/getcustomerproductpotentialpoints-1.md): `POST https://storefront.yotpo.com/loyalty/v3/stores/{store_id}/customer_product_potential_points` Calculates the potential points an authenticated customer can earn for a product and its variants. Requires customer authentication headers. Includes customer-specific multipliers (e.g. - [Product Potential Points](https://loyaltyapi.yotpo.com/v3.0/reference/getproductpotentialpoints-1.md): `POST https://storefront.yotpo.com/loyalty/v3/stores/{store_id}/product_potential_points` Calculates the potential points a customer can earn for a product and its variants. Does not require customer authentication. Returns points based on general earning rules. ## v3.0 · API reference · VIP Tiers - [Get VIP Tiers Program](https://loyaltyapi.yotpo.com/v3.0/reference/getviptiersprogram.md): `GET https://api.yotpo.com/loyalty/v3/stores/{store_id}/vip_tiers/programs/current` Returns the store's current VIP tiers program: its general settings and every tier with its criteria, rewards, and benefits. - [Get VIP Tiers Program Status](https://loyaltyapi.yotpo.com/v3.0/reference/getviptiersprogramstatus.md): `GET https://api.yotpo.com/loyalty/v3/stores/{store_id}/vip_tiers/programs/current:status` Returns the status of the store's current VIP tiers program. Check that the program is ACTIVE before pushing customers to a tier. - [Push Customer to Tier](https://loyaltyapi.yotpo.com/v3.0/reference/pushcustomertotier.md): `POST https://api.yotpo.com/loyalty/v3/stores/{store_id}/vip_tiers/customers/{customer_id}:push_to_tier` Manually assigns a customer to a VIP tier, either until a set end date or indefinitely.