🧭 Guidelines & Conventions

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

🌐 Protocol Support

Use HTTPS for every request. Requests sent over HTTP get a 301 redirect to HTTPS, and many HTTP clients turn a redirected POST into a GET, so writes sent over HTTP can fail.

🌍 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 private data or change state (for example, POST requests).
• Use api-cdn.yotpo.com for high-traffic, read-only endpoints used in shopper-facing interfaces, such as a product reviews widget.

🔑 Authentication at a Glance

See Authenticate and make your first call for how to get a token.

📄 Data Format

Request and response bodies use JSON, encoded as UTF-8. Send this header on every request that has a body:

Content-Type: application/json

A few endpoints return other formats, for example plain-text error messages and the HTML returned by the LLM schema endpoint. Each endpoint's reference page shows its response types.

📚 Pagination

Endpoints that return lists are paginated. The parameter names depend on the API family:

page starts at 1 everywhere except the Insights API. When you request more than the maximum, most endpoints silently return the maximum instead of an error, so check pagination.perPage (or per_page) in the response.

Example:

GET https://api-cdn.yotpo.com/v1/widget/YOUR_STORE_ID/products/YOUR_PRODUCT_ID/reviews.json?page=2&per_page=10

{
  "status": { "code": 200, "message": "OK" },
  "response": {
    "pagination": { "page": 2, "per_page": 10, "total": 756 },
    "reviews": []
  }
}

total is the total number of items across all pages, not the number of pages.

🚦 Rate Limiting

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

• If you exceed the allowed limit, you'll receive a 429 Too Many Requests error.
• Storefront limits are counted per IP address. Per-app-key limits are shared by everything that uses your store ID.
• 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. Read the headers instead of hard-coding a limit.

✅ Best Practices

To avoid hitting rate limits and ensure optimal API performance:

1. Monitor Rate Limit Headers: 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 (for example, Retrieve bottomline scores for a category page) to reduce the total number of API calls.

4. Cache Responses: For read-only operations, cache responses on your side. Responses are sent with Cache-Control: no-store, so your HTTP client and browser won't cache them for you.

5. Use Pagination Efficiently: When retrieving large datasets, use the page size limits above 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

Storefront data is not real-time. For example, Retrieve reviews for a product returns data with a delay of up to 3 hours, and new reviews also pass through your moderation settings before they appear. When a delay applies, it is documented on that endpoint's page.

📡 Status Codes and Errors

Yotpo APIs use standard HTTP status codes: 200 for success, 400 for an invalid request, 401 or 403 for a missing or invalid token, 404 for an unknown store, resource or path, 429 when you exceed a rate limit, and 500 for a server error.

Most api.yotpo.com errors return a status object with message, code, error_type and uuid. Log the uuid: it identifies the request if you contact Yotpo support. Some errors are plain text, and storefront endpoints return 200 with no data for an unknown product ID.

See Errors for every error body and how to handle each status code, and Testing your integration for how to test without affecting real shoppers.

🧩 Parameters Format

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

URL-encode query parameter values. For example, send + in an email address as %2B. Otherwise it is read as a space.

Product IDs must match the external product ID your store already sends to Yotpo (for example, the Shopify product ID or SKU), and support only letters, digits, _, and -.

✅ Final Tips

• Be sure to read endpoint-specific documentation for any extra requirements.
• Test against a dedicated test store before using production data. Write calls, such as creating reviews or deleting personal data, act on real data.
• Subscribe to the Changelog to hear about API and documentation changes.