Guidelines & conventions

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

Protocol support

The Core API supports only HTTPS requests.

Versioning

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.

Name spaces

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 & Email

Data format

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

Pagination

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 limit. page_info will be null.
• In the response, you'll receive the encoded page_info for the next page, as well as the results.
• In the next request, you can supply the page_info to get the next page.
• A request that includes the page_info parameter 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.

Rate limiting

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-Remaining header. 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 RateLimit-Reset header.

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.

Supported HTTP methods

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.

Parameter formats

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.

Yotpo & SMS web pixel

Yotpo’s SMS & Email web pixel enables you to send more personalized messages to your subscribers by tracking the actions they perform on your store.
The following actions are currently supported:

• Visited your site
• Viewed a product
• Added a product to their cart

To learn about installing the web pixel, see the following articles:

• Generic Yotpo SMS & Email Web Pixel Installation Guide
• Yotpo SMS & Email Web Pixel Installation Guide for Shopify Hydrogen 2