get
https://loyalty.yotpo.com/v3/stores//reward_instances
The Reward Instances API allows merchants to retrieve details of coupon-based rewards issued to their customers. This API supports querying reward instances based on discount type, expiration, and usage status.
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
Authentication and pagination
- Authenticate with your Yotpo access token in the
X-Yotpo-Tokenheader (how to generate one), not the Loyalty GUID and API key.discount_typeis required on the first request. To get the next page, send onlypage_info(thepagination.next_page_infovalue from the previous response); adding other filters to apage_inforequest returns400.usedtakestrueorfalse; omit it to get both.
Supported Discount Types
| Discount Type | Description |
|---|---|
| fixed_amount | Deducts a specific monetary value from the total price. |
| percentage | Applies a percentage-based discount to the total price. |
| generic_fixed_amount | Deducts a specific monetary value from the total price. |
Response Structure
Reward Instance Object
| Key | Type | Description |
|---|---|---|
| id | Number | The unique ID of the reward instance. |
| reward_option_id | Number | The ID of the reward option. |
| reward_text | String | The unique coupon code. |
| discount_type | String | Type of discount (fixed_amount, percentage). |
| used | Boolean | Indicates whether the reward has been used. |
| created_at | Date | The issue date of the reward. |
| expiration_date | Date | The expiration date (or NULL if there is no expiration or the data is unavailable). Only available for Shopify. |
| customer_id | Number | The ID of the customer linked to the reward (or NULL if unavailable). |
| customer_store_account_id | String | The store-specific customer ID (or NULL if unavailable). |
| customer_email | String | The email of the associated customer (or NULL if unavailable). |
| custom_fields | Object | Additional data relevant to the discount type. |
Custom Field Objects
| Key | Type | Applicable Discount Type | Description |
|---|---|---|---|
| value_cents | String | fixed_amount | The coupon's value in cents. |
| discount_percentage | Number | percentage | The discount percentage applied to the price. |
Pagination Object
| Key | Type | Description |
|---|---|---|
| next_page_info | String | Encoded information for retrieving the next set of results. |
Note
- Query param expiration_days is only available for Shopify merchants.
- If a merchant updates a coupon's expiration date after its creation, the API will not reflect the updated date.
- There's a rate limit of 300 requests per minute.