Skip to main content
POST
cURL
Required scope: write_reviewsThis endpoint is in preview, and is only available to partners and merchants who have opted-in
Use this endpoint to create a review in LoyaltyLion. When a review is created, if an applicable rule exists, it will be triggered based on the review’s status. If you are a review platform partner, use your platform identifier as the platform parameter. If you are a merchant integrating a custom reviews app, use custom. Reviews must be connected to a customer in LoyaltyLion, matched using their merchant_id. If you are a review partner, this must be the ID of the customer in the connected store, e.g. a Shopify customer ID.

Authorizations

Authorization
string
header
required

An API key linked to a Program in LoyaltyLion, with a set of permissions (scopes). API keys can be created manually, or acquired through an OAuth2 flow. The API key should be provided as a Bearer token in the Authorization header

Path Parameters

platform
string
required

The review platform. Use your platform identifier if you are a review partner, or "custom" if you are a merchant integrating a custom reviews app

Minimum string length: 1
Example:

"custom"

Query Parameters

site_id
number

Create the review in the specified site. This is only required for programs that have multiple sites. Programs with only a single site can omit this parameter, and the review will be created in the program's only site

Body

application/json

Body

merchant_id
string
required

The ID of the review in your review platform

Minimum string length: 1
customer
object
required

The customer who left the review

status
enum<string>
required

The current status of the review, which determines how and when associated rules are triggered. One of: pending (the review is pending review), flagged (the review has been flagged for review), approved (the review has been approved/published), rejected (the review has been rejected)

Available options:
approved,
flagged,
pending,
rejected
full_text
string
required

The full text of the review

Minimum string length: 1
rating
number
required

The rating given in the review

Required range: x >= 1
images_count
number
required

The number of images attached to the review

Required range: 0 <= x <= 1000
videos_count
number
required

The number of videos attached to the review

Required range: 0 <= x <= 1000
date
string
required

The date this review was created in the review platform, as an ISO 8601 timestamp

Example:

"2026-01-01T12:00:00Z"

product_merchant_id
string | null

If this review was for a specific product, this should be set to the product ID in your ecommerce platform. If you are a review partner, this must be the ID of the product in the connected store, e.g. a Shopify product ID

Minimum string length: 1
moderation_url
string<uri> | null

Optional URL to moderate the review in the review platform

Response

201

review
object
required