🧭 Guidelines & Conventions

Before building with the Yotpo Loyalty & Referrals API, review these conventions and limits.

📈 Rate Limiting

All API requests are rate-limited per merchant account, and the limit can differ between endpoint groups. Every response tells you your current limit and usage in the RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, X-RateLimit-Limit-Minute and X-RateLimit-Remaining-Minute headers. Going over the limit returns 429 Too Many Requests.

Read the headers instead of hard-coding a number, slow down when RateLimit-Remaining gets low, and spread bulk syncs over time. Errors explains each header and how to back off and retry.

⚠️ Errors

Validation errors return 422 (some endpoints return 400), a wrong or missing GUID or API key returns 401, and unknown resources return 404. Error bodies differ between v2.0 and v3.0 endpoints. Errors lists every status code with real error bodies, what to retry, and what to log for support.

🧪 Testing

There's no sandbox: every call, including Try It on these pages, reaches a real Loyalty program. Test with a separate store and example.com addresses. Testing your integration lists the calls that change points, send emails or create coupons, and includes a go-live checklist.

🔍 API Explorer Usage

Each API reference page includes:

• 📘 Live code examples on the right side
• 🔄 A language switcher for Curl, Ruby, Java — and for Events, JavaScript
• ✅ Ready-to-copy requests and responses for fast testing

These tools are great for learning the API and debugging requests. Try It sends real requests to the store whose credentials you enter, so use your test store.

✅ Next Steps

• Set up Authentication
• Pick a use case in What you can build
• Read Errors and Testing your integration before you go live