Authenticate and make your first call

You need two credentials from your Yotpo account: your store ID (also called app key) and your API secret. See Store ID and API Secret for where to find them.

Which calls need a token

Not every endpoint needs a token. Storefront endpoints are public, so your store ID in the URL is enough.

Each endpoint's reference page shows which method it uses.

1. Generate an access token

Call Yotpo authentication from your server with your store ID and API secret:

curl --request POST \
     --url https://api.yotpo.com/oauth/token \
     --header 'Content-Type: application/json' \
     --data '{
  "client_id": "YOUR_STORE_ID",
  "client_secret": "YOUR_API_SECRET",
  "grant_type": "client_credentials"
}'

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "bearer"
}

Store the token and reuse it. Don't request a new one for every call. If a call returns 401, generate a new token and retry the call once.

2. Make an authenticated call

Send the token in the X-Yotpo-Token header. For example, retrieve the most recent review:

curl --request GET \
     --url 'https://api.yotpo.com/v1/apps/YOUR_STORE_ID/reviews?count=1' \
     --header 'X-Yotpo-Token: YOUR_ACCESS_TOKEN' \
     --header 'Accept: application/json'

Without a valid token, merchant endpoints return:

{
  "status": {
    "message": "You are not authorized to access this page.",
    "code": 401,
    "error_type": "Exceptions::AccessDenied"
  }
}

A few endpoints return 403 with {"message": "Forbidden"} instead when the token is missing.

3. Make a public storefront call

Storefront endpoints need no token, so you can call them from server or browser code:

curl --request GET \
     --url 'https://api-cdn.yotpo.com/v3/storefront/store/YOUR_STORE_ID/product/YOUR_PRODUCT_ID/ratings'

{
  "bottomline": {
    "totalReviews": 128,
    "averageScore": 4.6,
    "totalOrganicReviews": 0,
    "organicAverageScore": 0.0
  }
}

Keep your credentials safe

• Keep the API secret and access tokens on your server, in a secrets manager or environment variables. Never put them in front-end code, mobile apps, or public repositories.
• Send credentials in headers, not in URLs, wherever the endpoint allows it. URLs end up in logs. Custom albums only accepts the token in the query string, so call it from your server and keep that URL out of your logs.
• The store ID is not a secret. It appears in every storefront URL.
• Only the account administrator can see the API secret. See Store ID and API Secret.