Which API version do I use?
Core and Reviews are moving from V1 to V3. Loyalty stays on V2, with a few V3 endpoints. Here's which to call for each product.
Each Yotpo product has its own API, and they're on different versions. Every reference page sits under the version in its URL, so the sidebar category (for example V3 · Orders & Fulfillments or Loyalty V2 · Orders) tells you which one you're looking at.
| Product | Use | Legacy | Notes |
|---|---|---|---|
| Core (orders, products, customers) | V3: api.yotpo.com/core/v3 | V1 | Not every V1 endpoint has a V3 version yet. Use V1 only for those. |
| Reviews (UGC) | V3 | V1 | Same as Core: V3 where it exists, V1 for the rest. |
| Reviews storefront display | Reviews storefront API V3: api-cdn.yotpo.com/v3/storefront | Reviews storefront API V1 | No token. Safe to call from the browser. |
| Loyalty | V2: loyalty.yotpo.com/api/v2 | None | V2 is the main Loyalty API. There's no plan to move Loyalty to V3. |
| Loyalty, V3 endpoints | V3, for a few features only | None | Reward instances, the VIP tiers program, points campaigns, and the storefront endpoints for points and the logged-in shopper's view. Use these alongside V2. |
| App partners | developers.yotpo.com | None | For apps that many merchants install. Uses OAuth 2.0, not a store's API secret. |
Core and Reviews: V1 to V3
V1 is legacy. New integrations should use V3, and existing integrations are moving to it. Some V1 endpoints don't have a V3 version yet, so a V3 integration may still call a few V1 endpoints. The same access token works for both: send it in the X-Yotpo-Token header.
Loyalty: V2
Loyalty V2 is the main version, and it isn't being replaced. It covers customers, orders, refunds, actions, redemptions, referrals and VIP tiers, with your Loyalty GUID and API key. See Loyalty authentication.
Loyalty also has a few V3 endpoints. They don't replace V2: use them only for the features they cover.
Authentication by version
| API | How to authenticate |
|---|---|
| Core and Reviews, V3 and V1 | Access token in the X-Yotpo-Token header. See Authenticate and make your first call. |
| Loyalty V2 | X-GUID and X-API-KEY headers. No token call. |
| Loyalty V3 (reward instances, VIP tiers program, points campaigns) | Access token in the X-Yotpo-Token header. |
| Storefront (Reviews and Loyalty) | No token. Logged-in shopper calls add X-Customer-Email and X-Customer-Token. |
| App partners | Per-store OAuth token in the X-Yotpo-Token header. See Generate access token. |
Updated 1 day ago