🧭 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 10 requests per second per merchant account.
If you exceed this limit, you'll receive a 429 Too Many Requests error.
All API responses include rate limiting headers that provide real-time information about your current usage and limits.

📊 Rate Limiting Headers

Every API response includes the following headers to help you monitor and manage your rate limit usage:

Header	Description
`ratelimit-limit`	The maximum number of requests allowed in the current time window
`ratelimit-remaining`	The number of requests remaining in the current time window
`ratelimit-reset`	The number of seconds until the rate limit window resets
`x-ratelimit-limit-minute`	The maximum number of requests allowed per minute
`x-ratelimit-remaining-minute`	The number of requests remaining in the current minute

Note: The actual values in these headers vary between API calls and depend on your current usage patterns.

⛑️ How to Avoid Rate Limiting

To prevent your application from hitting the rate limit:

✅ Monitor rate limit headers — Check ratelimit-remaining and x-ratelimit-remaining-minute on every response to track your usage
✅ Implement adaptive throttling — Use ratelimit-reset to calculate when to resume requests after approaching limits
✅ Optimize requests — Only fetch the data your app truly needs
✅ Use caching — Cache frequently accessed data to reduce API calls
✅ Regulate request frequency — Distribute requests across users and features to avoid bursts
✅ Handle 429 errors gracefully — Implement error handling for 429 responses and use retry-after logic
✅ Back off intelligently — When ratelimit-remaining is low, wait until ratelimit-reset seconds have passed before making more requests
✅ Include metadata in requests — Help monitor usage patterns (if available)

💡 Best Practice: Using Rate Limit Headers

Here's how to effectively use rate limiting headers in your application:

Check headers after each request — Read ratelimit-remaining to know how many requests you have left
Implement proactive throttling — When ratelimit-remaining drops below a threshold (e.g., 10), slow down your request rate
Respect reset times — Use ratelimit-reset to schedule requests after the window resets instead of immediately retrying
Monitor per-minute limits — Track x-ratelimit-remaining-minute to avoid short-term bursts that could trigger rate limits
Log header values — Include rate limit header values in your application logs to help debug and optimize usage patterns

Example implementation pattern:

// Pseudo-code example
const remaining = parseInt(response.headers['ratelimit-remaining']);
const resetIn = parseInt(response.headers['ratelimit-reset']);

if (remaining < 10) {
  // Slow down: wait until reset or add delay
  await delay(resetIn * 1000);
}

�� 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