--- title: "List rewards v2" method: GET path: "/v2/loyalties/rewards" tags: ["Rewards"] --- # List rewards v2 `GET /v2/loyalties/rewards` Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of rewards. Results can be filtered by id, name, type and created_at, and ordered by created_at or name (ascending or descending). The same field cannot be ordered both ascending and descending at the same time. ## Query parameters - `limit` integer, nullable - `order` union - string[] - '-created_at' | 'created_at' | 'name' | '-name' - `cursor` string, nullable - `filters` RewardListFilters — Filters for the rewards list. Each field accepts an object with a required `conditions` property. Conditions that are not supported for a given field type are rejected. - `junction` 'AND' | 'OR', nullable — How multiple field filters are combined. Defaults to AND behavior. - `id` RewardIdFilter — ID filter conditions. `$is`/`$is_not` accept a single value (string or 1-element array); `$in`/`$not_in` accept a string or an array of 1-100 values. All values must match the reward ID pattern `^lrew_[a-f0-9]+$`. - `conditions` object, required - `$is` union — Matches the exact reward ID. Single value (string or 1-element array). - string - string[] - `$is_not` union — Excludes the exact reward ID. Single value (string or 1-element array). - string - string[] - `$in` union — Matches any of the given reward IDs (up to 100). - string - string[] - `$not_in` union — Excludes all of the given reward IDs (up to 100). - string - string[] - `name` RewardStringFilter — String filter conditions. `$is`, `$is_not`, `$contains`, `$not_contain`, `$starts_with` and `$ends_with` accept a single value (string or 1-element array); `$in`/`$not_in` accept a string or an array of 1-10 values; `$has_value` and `$is_unknown` take no meaningful value (string or array with at most 1 item). - `conditions` object, required - `$is` union — Exact match. Single value (string or 1-element array). - string - string[] - `$is_not` union — Exact mismatch. Single value (string or 1-element array). - string - string[] - `$contains` union — Value contains the given substring. Single value (string or 1-element array). - string - string[] - `$not_contain` union — Value does not contain the given substring. Single value (string or 1-element array). - string - string[] - `$starts_with` union — Value starts with the given prefix. Single value (string or 1-element array). - string - string[] - `$ends_with` union — Value ends with the given suffix. Single value (string or 1-element array). - string - string[] - `$in` union — Value equals any of the given strings (up to 10). - string - string[] - `$not_in` union — Value equals none of the given strings (up to 10). - string - string[] - `$has_value` string, nullable — Field has a value. The condition value itself is ignored (string or array with at most 1 item). - `$is_unknown` string, nullable — Field has no value. The condition value itself is ignored (string or array with at most 1 item). - `type` RewardTypeFilter — Enum filter conditions for the reward `type` field. Allowed values are MATERIAL and DIGITAL. `$is`/`$is_not` accept a single value (string or 1-element array); `$in`/`$not_in` accept a string or an array of 1-10 values. - `conditions` object, required - `$is` union — Matches the exact type. - 'MATERIAL' | 'DIGITAL' - string[] - `$is_not` union — Excludes the exact type. - 'MATERIAL' | 'DIGITAL' - string[] - `$in` union — Matches any of the given types. - 'MATERIAL' | 'DIGITAL' - string[] - `$not_in` union — Excludes all of the given types. - 'MATERIAL' | 'DIGITAL' - string[] - `created_at` RewardDateFilter — Date filter conditions. `$before`/`$after` accept an ISO-8601 date string (or a 1-element array of one); `$is`, `$more_than` and `$less_than` accept a non-negative integer value passed as a string; `$has_value` and `$is_unknown` take no meaningful value. - `conditions` object, required - `$before` union — Date is before the given ISO-8601 date. - string - string[] - `$after` union — Date is after the given ISO-8601 date. - string - string[] - `$is` union — A non-negative integer value, passed as a string. - string - string[] - `$more_than` union — A non-negative integer value, passed as a string. - string - string[] - `$less_than` union — A non-negative integer value, passed as a string. - string - string[] - `$has_value` string, nullable — Field has a value. The condition value itself is ignored (string or array with at most 1 item). - `$is_unknown` string, nullable — Field has no value. The condition value itself is ignored (string or array with at most 1 item). ## Response `200` Cursor-paginated list of rewards. - RewardListResponse — Cursor-paginated list of rewards. - `data` RewardResponse[], required — The rewards on the current page. - `id` string, required — Unique reward identifier, prefixed with `lrew_`. - `name` string, required — Display name of the reward. - `type` 'MATERIAL' | 'DIGITAL', required — Reward type. - `status` 'ACTIVE' | 'DRAFT' | 'INACTIVE' | 'DELETED', required — Current lifecycle status of the reward. - `start_date` string, date-time, nullable — Date from which the reward is available, or `null` when not set. - `end_date` string, date-time, nullable — Date until which the reward is available, or `null` when not set. - `validity_hours` RewardValidityHoursResponse, required — Validity hours. `daily` is present only when `type` is DAILY; omitted otherwise. - `type` 'DAILY' | 'ANY_TIME', required — Whether the reward is purchasable at any time or only during specific daily windows. - `daily` RewardValidityDailyHoursResponse[] — Daily time windows. Present only when `type` is DAILY. - `days_of_week` integer[], required — Days of the week the window applies to, as integers 0-6 (0 = Sunday). - `start_time` string, required — Window start time in `HH:mm` format. - `end_time` string, required — Window end time in `HH:mm` format. - `material` RewardMaterialResponse — Material reward definition. - `type` 'PRODUCT' | 'SKU', required — Kind of material reward. - `product` RewardMaterialProductResponse — Product reference. - `id` string, required — Product identifier, prefixed with `prod_`. - `sku` RewardMaterialSKUResponse — SKU reference. - `product_id` string, required — Unique identifier of the product the SKU belongs to, prefixed with `prod_`. - `id` string, required — SKU identifier, prefixed with `sku_`. - `digital` RewardDigitalResponse — Digital reward definition. Only the object matching `type` is present; the others are omitted. - `type` 'DISCOUNT_COUPONS' | 'GIFT_VOUCHERS' | 'LOYALTY_CARD_POINTS', required — Kind of digital reward. - `discount_coupons` RewardDigitalDiscountCouponsResponse — Discount coupons configuration. - `campaign_id` string, required — Unique identifier of the discount coupons campaign, prefixed with `camp_`. - `gift_vouchers` RewardDigitalGiftVouchersResponse — Gift vouchers configuration. - `campaign_id` string, required — Unique identifier of the gift vouchers campaign, prefixed with `camp_`. - `balance` number, required — Gift card balance credited when the reward is delivered. - `loyalty_card_points` RewardDigitalLoyaltyCardPointsResponse — Loyalty card points configuration. - `points` integer, required — Number of points credited when the reward is delivered. - `card_definition_id` string, required — Unique identifier of the card definition points are credited to, prefixed with `lcdef_`. - `refunds` RewardRefundsResponse, required — Refund policy. - `type` 'NONE' | 'REFUNDABLE', required — Whether reward purchases can be refunded. Defaults to NONE. - `costs` RewardCostResponse[], required — Point costs of the reward. Empty array when no costs are defined. - `id` string, required — Unique cost identifier, prefixed with `lrcst_`. - `rules` RewardCostRuleGroupResponse — Rules group. Contains a `logic` formula string plus numbered rule definition properties (positive-integer keys). - `logic` string — Logical formula combining the numbered rule definitions, e.g. `"1 AND 2"`. - `spending` RewardCostSpendingResponse[], nullable — Points spending definitions, or `null` when none are defined. - `id` string, required — Unique spending identifier, prefixed with `lrspn_`. Assigned by the API when omitted on create/update. - `name` string, nullable — Optional display name of the spending definition, or `null`. - `points` integer, required — Number of points the member must spend. - `card_definition_id` string, required — Unique identifier of the card definition the points are spent from, prefixed with `lcdef_`. - `purchase_limits` RewardPurchaseLimits, required — Limits on how often a member can purchase the reward. Always present on reward responses; defaults to no cooldown and no frequency limit. - `cooldown` RewardPurchaseLimitsCooldown — Purchase cooldown limits for a reward. - `type` 'NO_COOLDOWN' | 'FIXED_COOLDOWN', required — Cooldown type. `NO_COOLDOWN` - no cooldown. `FIXED_COOLDOWN` - wait a fixed period after each purchase. - `fixed_cooldown` RewardPurchaseLimitsCooldownFixedCooldown — Fixed cooldown configuration. - `period` RewardPurchaseLimitsCooldownFixedCooldownPeriod, required — Fixed cooldown period after a reward purchase. - `value` integer, required — Length of the cooldown period. - `unit` 'HOUR' | 'DAY' | 'WEEK' | 'MONTH' | 'YEAR', required — Unit of the cooldown period. - `frequency` RewardPurchaseLimitsFrequency — Purchase frequency limits for a reward. - `type` 'NO_LIMIT' | 'LIMITED', required — Frequency limit type. `NO_LIMIT` - unlimited purchases. `LIMITED` - limited by the `limits` array. - `limits` RewardPurchaseLimitsFrequencyLimit[], required — Frequency limit definitions. Empty array when `type` is `NO_LIMIT`; one entry when `type` is `LIMITED`. - `type` 'TIME_BASED', required — Limit type. Always `TIME_BASED`. - `period` CardDefinitionLimitTimeBasedPeriod, required — Time-based limit period. - `type` 'CURRENT_PERIOD', required — Period type. - `current_period` object — Current-period configuration. Present when `type` is `CURRENT_PERIOD`. - … - `triggers` RewardPurchaseLimitsFrequencyLimitTriggers, required — Maximum number of purchases allowed in the period. - `max` integer, required — Maximum number of purchases in the configured period. - `metadata` object, required — Arbitrary key-value metadata attached to the reward. Empty object when not set. - `created_at` string, date-time, required — Timestamp when the reward was created (ISO-8601). - `updated_at` string, date-time, nullable — Timestamp when the reward was last updated (ISO-8601), or `null` when never updated. - `object` 'reward', required — Object type marker; always `reward`. - `cursor` RewardListCursor, required — Pagination cursor. - `next` string, required — Cursor value to pass as the `cursor` query parameter to fetch the next page. - `expires_at` string, date-time — Timestamp when the cursor expires. - `object` 'list', required — Object type marker; always `list`. ## Other responses - `400` — Validation error - request body or query parameters failed validation, or the operation is not allowed in the current resource state. - `404` — Resource not found. - `409` — Conflict - e.g. duplicate resource or invalid state transition. - `500` — Internal server error. --- [API](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-loyalty-v2-api/revisions/69be73b5cff0/schema)