🧭 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.

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

Base URL	Description
`https://api.yotpo.com`	Core API for secure, authenticated operations (e.g., login, submissions).
`https://api-cdn.yotpo.com`	CDN-backed API optimized for storefront display, offering cached responses.

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).

All request and response bodies must use JSON format.

Include the following HTTP header in all API requests:

For endpoints that return large datasets, use pagination parameters:

Parameter	Description
`page`	The page number to retrieve (default is 1)
`count`	Number of items to return per page

Example:

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.

API responses include rate limiting headers that provide real-time information about your current 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 time (in seconds) until the rate limit 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:
Rate limit values vary between endpoints and may change based on your account tier or usage patterns.

To avoid hitting rate limits and ensure optimal API performance:

Monitor Rate Limit Headers: Always check the ratelimit-remaining header in responses to track your usage and avoid unexpected throttling.
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).
Batch Requests When Possible: Instead of making multiple individual requests, use batch endpoints or combine operations to reduce the total number of API calls.
Cache Responses: For read-only operations, cache responses locally to minimize API calls, especially for data that doesn't change frequently.
Use Pagination Efficiently: When retrieving large datasets, use appropriate page and per_page values to minimize the number of requests needed.
Handle Errors Gracefully: Implement proper error handling for 429 responses, including logging and alerting, so you can adjust your request patterns proactively.

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.

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

Response Code	Status Description
`200`	Successful response
`401`	Unauthorized – Authentication required
`500`	Internal server error (e.g., timeout)

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

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

Parameter	Format	Example
`email`	`user@domain`	`jsmith@yotpo.com`
`URL`	Full URL	`http://www.gkshops.com/USBthingy.html`
`Date`	`YYYY-MM-DD`	`2017-12-31`

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

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.