🧭 Guidelines & Conventions

Before you start using the Yotpo API, we recommend reviewing these key guidelines to ensure a smooth development experience.

🌐 Protocol Support

Yotpo’s API supports both HTTP and HTTPS requests.

⚠️

We strongly recommend using HTTPS in production to secure your API traffic.

🌍 Base URLs

Yotpo provides two base URLs depending on the type of operation:

📌 When to Use Each

• Use api.yotpo.com for operations that involve sensitive data or modify state (e.g., POST requests).
• Use api-cdn.yotpo.com for high-performance, read-only endpoints used in client-facing interfaces (e.g., product reviews widgets).

📄 Data Format

All request and response bodies must use JSON format.

Include the following HTTP header in all API requests:

📚 Pagination

For endpoints that return large datasets, use pagination parameters:

Example:

🚦 Rate Limiting

To ensure stability and fairness, some API endpoints are rate-limited.

• If you exceed the allowed limit, you'll receive a 429 Too Many Requests error.
• Where applicable, rate limits are documented per endpoint.

📊 Rate Limit Headers

API responses include rate limiting headers that provide real-time information about your current usage:

📘

Note:
Rate limit values vary between endpoints and may change based on your account tier or usage patterns.

✅ Best Practices

To avoid hitting rate limits and ensure optimal API performance:

1. Monitor Rate Limit Headers: Always check the ratelimit-remaining header in responses to track your usage and avoid unexpected throttling.

2. Implement Exponential Backoff: If you receive a 429 Too Many Requests error, wait before retrying. Use the ratelimit-reset header to determine when to retry, or implement exponential backoff (e.g., wait 1 second, then 2 seconds, then 4 seconds).

3. Batch Requests When Possible: Instead of making multiple individual requests, use batch endpoints or combine operations to reduce the total number of API calls.

4. Cache Responses: For read-only operations, cache responses locally to minimize API calls, especially for data that doesn't change frequently.

5. Use Pagination Efficiently: When retrieving large datasets, use appropriate page and per_page values to minimize the number of requests needed.

6. Handle Errors Gracefully: Implement proper error handling for 429 responses, including logging and alerting, so you can adjust your request patterns proactively.

📈 Data Freshness SLA

Some endpoints come with a Service Level Agreement (SLA) that guarantees timely or "fresh" data.

If an SLA applies, it will be clearly documented under that specific endpoint.

📡 Status Codes

Yotpo APIs use standard HTTP response codes to indicate the outcome of requests:

📘

Note:
Some endpoints may return additional error codes for specific cases. These are detailed in the respective endpoint documentation.

🧩 Parameters Format

Make sure all parameters follow the correct format to avoid failed requests.

🌐 UTF-8 Support

Yotpo APIs support UTF-8 encoding, including special characters in parameters and payloads.

✅ Final Tips

• Be sure to read endpoint-specific documentation for any extra requirements.
• Always test in a staging environment before using production data.
• Bookmark this section for quick reference when implementing or debugging API calls.