🧭 Guidelines & Conventions

Before building with the Yotpo Loyalty & Referrals API, we recommend reviewing the following best practices, usage patterns, and limitations.

📈 Rate Limiting

To ensure fair usage and system stability, all API requests are rate-limited.

• You can make up to 5 requests per second per merchant account.
• If you exceed this limit, you'll receive a 429 Too Many Requests error.
• The response includes a RateLimit-Remaining header that shows how many requests are left in the current window.

⛑️ How to Avoid Rate Limiting

To prevent your application from hitting the rate limit:

• ✅ Optimize requests to only fetch the data your app truly needs
• ✅ Use caching for frequently accessed data
• ✅ Regulate request frequency across users and features
• ✅ Implement error handling for 429 responses and use retry-after logic
• ✅ Include metadata in your requests to help monitor usage (if available)
• ✅ Back off and retry after a short delay when errors occur

🧪 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, debugging quickly, or testing requests before integrating into your app.

🧩 Coming Soon

Additional conventions — like error codes, pagination, and response structure — may be documented here in the future.

✅ Next Steps

• Set up Authentication
• Explore available API endpoints