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 Reviews and Visual UGC. It is more up to date with a modern framework, less error-prone, and easier to debug, if needed.

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

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 and errors

The limit is 5 requests per second per store; going over returns 429. Every response includes RateLimit-Remaining and RateLimit-Reset (seconds until the window resets). See Rate limiting for pacing and bulk syncs, and Errors for every status code, error body and retry rule.

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.