Before you start using the API, we recommend you review these guidelines.
The Core API supports only HTTPS requests.
The Core API is currently available in two versions:
- Version 1.0 includes endpoints which are specific to the Reviews and Visual UGC products.
- Version 3.0 includes endpoints that can be used to sync your store information across to Yotpo for multiple Yotpo product lines.
Going forward, we'll be versioning all changes to our API, making it simpler for you to identify the most suitable version for your use case.
To make clear which product line each endpoint applies to, each URL contains a name space by product line.
- core - Shared resources across Yotpo product lines
- reviews - Reviews
- vms - Visual UGC
- messaging - SMS Marketing
Data must be in JSON format. As such, the HTTP header content-type must be set to application/json.
The Core API supports cursor-based pagination.
Use the following parameters to paginate results in API requests which support pagination:
page_info - The page info
limit - The number of results to return (max. 100)
- In the first request, supply the
page_infowill be null.
- In the response, you'll receive the encoded
page_infofor the next page, as well as the results.
- In the next request, you can supply the
page_infoto get the next page.
- A request that includes the
page_infoparameter should not include any other parameters except for
limit. If you want your results to be filtered by other parameters, you'll need to include those parameters in the first request you make.
To improve the experience for all our users, we impose a limit of 5 requests/second on API requests. This limit applies per store. You’ll receive a
429 Too Many Requests error message if you reach this limit.
- You can check how many requests you have left using the
RateLimit-Remainingheader. This header is sent in response to your API request.
- If you reach the rate limit, you can check how many seconds you need to wait before sending the next request by using the
To avoid rate limit errors, we recommend you follow these best practices:
- Optimize your code to only get the data that your app requires.
- Use caching for data that your app uses often.
- Regulate the rate of your requests for smoother distribution.
- Include code that catches errors. If you ignore these errors and keep trying to make requests, then your app won’t be able to gracefully recover.
- Use metadata about your app’s API usage, included with all API responses, to manage your app’s behavior dynamically.
- Your code should stop making additional API requests until enough time has passed to retry. The recommended backoff time is 1 second.
The Core API lets you create, view, update, or delete resources using the following standard HTTP method requests:
- GET - Retrieves information about a resource.
- POST - Creates a resource.
- DELETE - Deletes the specified resources.
- PATCH - Partially updates an existing resource. Use this method to provide the list of changes to be applied to the resource requested. To clear a field, leave the value empty.
The Core API calls support special characters according to the UTF-8 coding.
Parameters you send in the calls must be in the correct format or the call will not be processed.
|Country code||Must be valid ISO code of 2 characters.|
|Currency||Must be valid ISO code of 3 characters. See currency codes||USD|
|Date||ISO 8601. Learn more||2020-10-25|
|Datetime||ISO 8601. Learn more|
Datetimes always use the UTC timezone (as indicated by the Z at the end of the datetime value).
|Language||ISO 639-1. Learn more|
|A valid email address.||[email protected]|
|URL||A valid URL.||http://example.com/page.html|
|Phone number||E.164. Learn more||+14155552671|