Guidelines and Conventions

Before you start using the API, we recommend you review these guidelines.

Protocol support

Use HTTPS. An http:// request gets a 301 redirect to https://, and many HTTP clients turn a redirected POST into a GET, so a POST sent over HTTP can fail.

UTF-8 Support

The Yotpo API calls support special characters according to the UTF-8 coding.

Data Format

Data must be in JSON format. As such, the HTTP header content-type must be set to: application/json

Pagination

Two pagination styles are in use, depending on the endpoint:

Endpoints	Parameters	How to get the next page
`/core/v3/...` (orders, fulfillments, products, variants, customers)	`limit` (1 to 100, default 100) and `page_info`	Send the `pagination.next_page_info` value from the response as `page_info`. When it's `null`, you've reached the last page.
`/v2/{account_id}/...` (reviews, products, questions, orders)	`page` (page number) and `count` (results per page)	Increase `page` by 1 until a page returns fewer than `count` results.

Rate limiting

Rate limits apply to your app per store: each store your app is installed on has its own allowance. They depend on the endpoint:

Endpoints	Limit
`/core/v3/...`: orders, fulfillments, products, variants, customers, segments, webhooks	5 requests per second
`/v2/{store_id}/moderation/reviews`	5 requests per second
`/loyalty/v3/...`, and the token and Remove Application endpoints	100 requests per minute and 6,000 per hour
Other `/v2/...` endpoints: reviews, products, questions, comments	20,000 requests per minute and 1,000,000 per hour

A few stores have lower limits for some endpoints. Always go by the headers below rather than the table.

Every response tells you where you stand:

Header	Meaning
`RateLimit-Limit`	The limit for the current window.
`RateLimit-Remaining`	Requests left in the current window.
`RateLimit-Reset`	Seconds until the window resets.
`X-RateLimit-Limit-Second`, `X-RateLimit-Limit-Minute`, `X-RateLimit-Limit-Hour`	The limit for each window that applies to the endpoint.
`X-RateLimit-Remaining-Second`, `-Minute`, `-Hour`	Requests left in each of those windows.

Over the limit, you get 429 with a Retry-After header (seconds to wait):

{
  "message": "API rate limit exceeded",
  "request_id": "41c1544aa131c145725e5862fea4c031"
}

To stay within the limits:

Wait for Retry-After seconds before retrying, and spread requests out rather than sending them in bursts.
Only fetch the data your app needs, and cache data that changes rarely.
Watch RateLimit-Remaining and slow down before it reaches 0.

Parameters

Email and URL parameters you send in the calls must be in the correct format.

Parameter	Format
`email`	[email protected]
`url`	http://www.domain.com/full_path_of_resource
`date`	YYYY-MM-DD

Status codes and errors

The API uses standard HTTP status codes. Errors lists the codes it returns, the exact error bodies, and how to handle each one.