> ## Documentation Index > Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt > Use this file to discover all available pages before exploring further. # List loyalty rewards > ⚠️ **BETA endpoint** This is a work-in-progress documentation of a BETA endpoint. The parameters, fields, request and response bodies, and other data may subject to change. If you want to share feedback or improvements, contact Voucherify 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. ## OpenAPI ````yaml /openapi/loyalties-v2.json get /v2/loyalties/rewards openapi: 3.1.0 info: title: Voucherify Loyalty v2 API version: 2.0.0 description: >- Complete OpenAPI specification for the Voucherify Loyalty v2 API. All endpoints require the LOYALTY_V2 feature flag. Combined from per-domain specs: programs.yaml, members.yaml, program-operations.yaml, card-definitions.yaml, earning-rules.yaml, tier-structures.yaml, benefits.yaml, rewards.yaml, examine.yaml servers: - url: '{protocol}://{host}' variables: protocol: default: https enum: - https - http host: default: api.voucherify.io security: - bearerAuth: [] X-App-Id: [] X-App-Token: [] tags: - name: Programs description: >- Loyalty program CRUD, lifecycle management, program-scoped resource assignments (card definitions, earning rules, rewards, tier structures), member management (create, list, get, activate, deactivate, delete), card operations (points adjustment, pending points, expiring points, transactions), reward purchases, and activity history. - name: Card Definitions description: >- CRUD operations, lifecycle management, and activity history for card definitions. Card definitions describe the configuration for loyalty cards, including code generation, points expiration, earning/spending limits, pending points, refunds, and balance settings. - name: Earning Rules description: >- Manage earning rules that define how customers earn points or receive incentives based on triggers (events, segments, custom events). Includes CRUD, lifecycle, and activity history. - name: Tier Structures description: >- CRUD operations, lifecycle management, and activity history for tier structures. Includes nested tier definitions (create, list, update, delete) within tier structures. Tier structures define the tiering model for loyalty programs — how members qualify for and move between tiers. - name: Benefits description: >- Manage benefit definitions (fixed points, proportional points, material, digital). Includes CRUD, lifecycle transitions, and activity history. - name: Rewards description: >- CRUD, lifecycle operations, and activity history for reward definitions. Rewards can be material (product/SKU) or digital (discount coupons, gift vouchers). - name: Examine description: >- Evaluation endpoints that estimate earning opportunities and reward availability for a customer across their loyalty program memberships, without side effects. paths: /v2/loyalties/rewards: get: tags: - Rewards summary: List loyalty rewards description: > ⚠️ **BETA endpoint** This is a work-in-progress documentation of a BETA endpoint. The parameters, fields, request and response bodies, and other data may subject to change. If you want to share feedback or improvements, contact Voucherify 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. operationId: listRewards parameters: - name: limit in: query required: false description: | Maximum number of rewards to return. Must be between 1 and 100. Defaults to 10 when not provided. schema: type: - integer - 'null' minimum: 1 maximum: 100 default: 10 - name: order in: query required: false description: > Field(s) to order results by. Prefix with `-` for descending order. Accepts a single value or an array of values. Defaults to `-created_at`. The same field cannot be used in both ascending and descending order at once. schema: oneOf: - type: array items: type: string enum: - '-created_at' - created_at - name - '-name' - type: string enum: - '-created_at' - created_at - name - '-name' - type: 'null' - name: cursor in: query required: false description: > Pagination cursor returned in the `cursor.next` field of a previous response. Must match the pattern `^lcrsrew_[a-f0-9]+$`. schema: type: - string - 'null' pattern: ^lcrsrew_[a-f0-9]+$ - name: filters in: query required: false style: deepObject explode: true description: > Field-specific filter conditions, passed as a deep object, e.g. `filters[name][conditions][$contains]=gift`. See the `RewardListFilters` schema for available fields and conditions. schema: oneOf: - $ref: '#/components/schemas/RewardListFilters' - type: 'null' responses: '200': description: Cursor-paginated list of rewards. content: application/json: schema: $ref: '#/components/schemas/RewardListResponse' '400': description: >- Validation error - request body or query parameters failed validation, or the operation is not allowed in the current resource state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflict - e.g. duplicate resource or invalid state transition. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: RewardListFilters: type: object description: > 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. properties: junction: description: How multiple field filters are combined. Defaults to AND behavior. oneOf: - type: string enum: - AND - OR - type: 'null' id: description: >- Filter by reward ID (ID field type). Values must match `^lrew_[a-f0-9]+$`. oneOf: - $ref: '#/components/schemas/RewardIdFilter' - type: 'null' name: description: Filter by reward name (string field type). oneOf: - $ref: '#/components/schemas/RewardStringFilter' - type: 'null' type: description: >- Filter by reward type (enum field type with values MATERIAL, DIGITAL). oneOf: - $ref: '#/components/schemas/RewardTypeFilter' - type: 'null' created_at: description: Filter by creation date (date field type). oneOf: - $ref: '#/components/schemas/RewardDateFilter' - type: 'null' additionalProperties: false RewardListResponse: type: object description: Cursor-paginated list of rewards. properties: data: type: array description: The rewards on the current page. items: $ref: '#/components/schemas/RewardResponse' cursor: description: Pagination cursor, or null when there are no more results. oneOf: - $ref: '#/components/schemas/RewardListCursor' - type: 'null' object: type: string const: list description: Object type marker; always `list`. required: - data - cursor - object ErrorResponse: type: object description: Standard error response returned by all Loyalty v2 endpoints. properties: code: type: integer description: HTTP status code of the error. key: type: string description: Machine-readable error key. message: type: string description: Human-readable error message. details: type: string description: Additional details about the error. request_id: type: string description: Identifier of the request that produced the error. RewardIdFilter: type: object description: > 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]+$`. properties: conditions: type: object minProperties: 1 additionalProperties: false properties: $is: description: >- Matches the exact reward ID. Single value (string or 1-element array). oneOf: - type: string pattern: ^lrew_[a-f0-9]+$ - type: array items: type: string pattern: ^lrew_[a-f0-9]+$ minItems: 1 maxItems: 1 - type: 'null' $is_not: description: >- Excludes the exact reward ID. Single value (string or 1-element array). oneOf: - type: string pattern: ^lrew_[a-f0-9]+$ - type: array items: type: string pattern: ^lrew_[a-f0-9]+$ minItems: 1 maxItems: 1 - type: 'null' $in: description: Matches any of the given reward IDs (up to 100). oneOf: - type: string pattern: ^lrew_[a-f0-9]+$ - type: array items: type: string pattern: ^lrew_[a-f0-9]+$ minItems: 1 maxItems: 100 - type: 'null' $not_in: description: Excludes all of the given reward IDs (up to 100). oneOf: - type: string pattern: ^lrew_[a-f0-9]+$ - type: array items: type: string pattern: ^lrew_[a-f0-9]+$ minItems: 1 maxItems: 100 - type: 'null' required: - conditions additionalProperties: false RewardStringFilter: type: object description: > 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). properties: conditions: type: object minProperties: 1 additionalProperties: false properties: $is: description: Exact match. Single value (string or 1-element array). oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $is_not: description: Exact mismatch. Single value (string or 1-element array). oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $contains: description: >- Value contains the given substring. Single value (string or 1-element array). oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $not_contain: description: >- Value does not contain the given substring. Single value (string or 1-element array). oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $starts_with: description: >- Value starts with the given prefix. Single value (string or 1-element array). oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $ends_with: description: >- Value ends with the given suffix. Single value (string or 1-element array). oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $in: description: Value equals any of the given strings (up to 10). oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 10 - type: 'null' $not_in: description: Value equals none of the given strings (up to 10). oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 10 - type: 'null' $has_value: description: >- Field has a value. The condition value itself is ignored (string or array with at most 1 item). oneOf: - type: string - type: array maxItems: 1 - type: 'null' $is_unknown: description: >- Field has no value. The condition value itself is ignored (string or array with at most 1 item). oneOf: - type: string - type: array maxItems: 1 - type: 'null' required: - conditions additionalProperties: false RewardTypeFilter: type: object description: > 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. properties: conditions: type: object minProperties: 1 additionalProperties: false properties: $is: description: Matches the exact type. oneOf: - type: string enum: - MATERIAL - DIGITAL - type: array minItems: 1 maxItems: 1 items: type: string enum: - MATERIAL - DIGITAL - type: 'null' $is_not: description: Excludes the exact type. oneOf: - type: string enum: - MATERIAL - DIGITAL - type: array minItems: 1 maxItems: 1 items: type: string enum: - MATERIAL - DIGITAL - type: 'null' $in: description: Matches any of the given types. oneOf: - type: string enum: - MATERIAL - DIGITAL - type: array minItems: 1 maxItems: 10 items: type: string enum: - MATERIAL - DIGITAL - type: 'null' $not_in: description: Excludes all of the given types. oneOf: - type: string enum: - MATERIAL - DIGITAL - type: array minItems: 1 maxItems: 10 items: type: string enum: - MATERIAL - DIGITAL - type: 'null' required: - conditions additionalProperties: false RewardDateFilter: type: object description: > 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. properties: conditions: type: object minProperties: 1 additionalProperties: false properties: $before: description: Date is before the given ISO-8601 date. oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $after: description: Date is after the given ISO-8601 date. oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $is: description: A non-negative integer value, passed as a string. oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $more_than: description: A non-negative integer value, passed as a string. oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $less_than: description: A non-negative integer value, passed as a string. oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $has_value: description: >- Field has a value. The condition value itself is ignored (string or array with at most 1 item). oneOf: - type: string - type: array maxItems: 1 - type: 'null' $is_unknown: description: >- Field has no value. The condition value itself is ignored (string or array with at most 1 item). oneOf: - type: string - type: array maxItems: 1 - type: 'null' required: - conditions additionalProperties: false RewardResponse: type: object description: A reward, as returned by the API. properties: id: type: string pattern: ^lrew_[a-f0-9]+$ description: Unique reward identifier, prefixed with `lrew_`. name: type: string description: Display name of the reward. type: type: string enum: - MATERIAL - DIGITAL description: Reward type. status: type: string enum: - ACTIVE - DRAFT - INACTIVE - DELETED description: Current lifecycle status of the reward. start_date: type: - string - 'null' format: date-time description: Date from which the reward is available, or null when not set. end_date: type: - string - 'null' format: date-time description: Date until which the reward is available, or null when not set. validity_hours: $ref: '#/components/schemas/RewardValidityHoursResponse' description: >- Hours during which the reward can be purchased. Always present; defaults to `{ "type": "ANY_TIME" }`. material: $ref: '#/components/schemas/RewardMaterialResponse' description: >- Material reward definition. Present only when `type` is MATERIAL; omitted otherwise. digital: $ref: '#/components/schemas/RewardDigitalResponse' description: >- Digital reward definition. Present only when `type` is DIGITAL; omitted otherwise. refunds: $ref: '#/components/schemas/RewardRefundsResponse' description: 'Refund policy. Always present; defaults to `{ "type": "NONE" }`.' costs: type: array description: Point costs of the reward. Empty array when no costs are defined. items: $ref: '#/components/schemas/RewardCostResponse' metadata: type: object description: >- Arbitrary key-value metadata attached to the reward. Empty object when not set. created_at: type: string format: date-time description: Timestamp when the reward was created (ISO-8601). updated_at: type: - string - 'null' format: date-time description: >- Timestamp when the reward was last updated (ISO-8601), or null when never updated. object: type: string const: reward description: Object type marker; always `reward`. required: - id - name - type - status - validity_hours - refunds - costs - metadata - created_at - object RewardListCursor: type: object description: Pagination cursor. properties: next: type: string description: >- Cursor value to pass as the `cursor` query parameter to fetch the next page. expires_at: type: string format: date-time description: Timestamp when the cursor expires. required: - next RewardValidityHoursResponse: type: object description: >- Validity hours. `daily` is present only when `type` is DAILY; omitted otherwise. properties: type: type: string enum: - DAILY - ANY_TIME description: >- Whether the reward is purchasable at any time or only during specific daily windows. daily: type: array description: Daily time windows. Present only when `type` is DAILY. items: $ref: '#/components/schemas/RewardValidityDailyHoursResponse' required: - type RewardMaterialResponse: type: object description: Material reward definition. properties: type: type: string enum: - PRODUCT - SKU description: Kind of material reward. product: $ref: '#/components/schemas/RewardMaterialProductResponse' description: >- Product delivered by the reward. Present only when `type` is PRODUCT; omitted otherwise. sku: $ref: '#/components/schemas/RewardMaterialSKUResponse' description: >- SKU delivered by the reward. Present only when `type` is SKU; omitted otherwise. required: - type RewardDigitalResponse: type: object description: >- Digital reward definition. Only the object matching `type` is present; the others are omitted. properties: type: type: string enum: - DISCOUNT_COUPONS - GIFT_VOUCHERS - LOYALTY_CARD_POINTS description: Kind of digital reward. discount_coupons: $ref: '#/components/schemas/RewardDigitalDiscountCouponsResponse' description: >- Discount coupons configuration. Present only when `type` is DISCOUNT_COUPONS. gift_vouchers: $ref: '#/components/schemas/RewardDigitalGiftVouchersResponse' description: >- Gift vouchers configuration. Present only when `type` is GIFT_VOUCHERS. loyalty_card_points: $ref: '#/components/schemas/RewardDigitalLoyaltyCardPointsResponse' description: >- Loyalty card points configuration. Present only when `type` is LOYALTY_CARD_POINTS. required: - type RewardRefundsResponse: type: object description: Refund policy. properties: type: type: string enum: - NONE - REFUNDABLE description: Whether reward purchases can be refunded. Defaults to NONE. required: - type RewardCostResponse: type: object description: | A reward cost. `rules` is omitted when the cost has no rule definitions; `spending` is null when no spending is defined. properties: id: type: string pattern: ^lrcst_[a-f0-9]+$ description: Unique cost identifier, prefixed with `lrcst_`. rules: $ref: '#/components/schemas/RewardCostRuleGroupResponse' description: >- Rules guarding this cost. Omitted when the cost has no rule definitions. spending: type: - array - 'null' description: Points spending definitions, or null when none are defined. items: $ref: '#/components/schemas/RewardCostSpendingResponse' required: - id RewardValidityDailyHoursResponse: type: object description: A single daily validity window. properties: days_of_week: type: array description: >- Days of the week the window applies to, as integers 0-6 (0 = Sunday). items: type: integer minimum: 0 maximum: 6 start_time: type: string description: Window start time in `HH:mm` format. example: '09:00' end_time: type: string description: Window end time in `HH:mm` format. example: '17:00' required: - days_of_week - start_time - end_time RewardMaterialProductResponse: type: object description: Product reference. properties: id: type: string pattern: ^prod_[a-f0-9]+ description: Product identifier, prefixed with `prod_`. required: - id RewardMaterialSKUResponse: type: object description: SKU reference. properties: product_id: type: string pattern: ^prod_[a-f0-9]+ description: Identifier of the product the SKU belongs to, prefixed with `prod_`. id: type: string pattern: ^sku_[a-f0-9]+ description: SKU identifier, prefixed with `sku_`. required: - product_id - id RewardDigitalDiscountCouponsResponse: type: object description: Discount coupons configuration. properties: campaign_id: type: string pattern: ^camp_[a-zA-Z0-9]+ description: Identifier of the discount coupons campaign, prefixed with `camp_`. required: - campaign_id RewardDigitalGiftVouchersResponse: type: object description: Gift vouchers configuration. properties: campaign_id: type: string pattern: ^camp_[a-zA-Z0-9]+ description: Identifier of the gift vouchers campaign, prefixed with `camp_`. balance: type: number description: Gift card balance credited when the reward is delivered. required: - campaign_id - balance RewardDigitalLoyaltyCardPointsResponse: type: object description: Loyalty card points configuration. properties: points: type: integer description: Number of points credited when the reward is delivered. card_definition_id: type: string pattern: ^lcdef_[a-f0-9]+$ description: >- Identifier of the card definition points are credited to, prefixed with `lcdef_`. required: - points - card_definition_id RewardCostRuleGroupResponse: type: object description: | Rules group. Contains a `logic` formula string plus numbered rule definition properties (positive-integer keys). properties: logic: type: string description: >- Logical formula combining the numbered rule definitions, e.g. `"1 AND 2"`. patternProperties: ^[1-9]\d*$: $ref: '#/components/schemas/RewardCostRuleDefinitionResponse' RewardCostSpendingResponse: type: object description: Points spending definition. properties: points: type: integer description: Number of points the member must spend. card_definition_id: type: string pattern: ^lcdef_[a-f0-9]+$ description: >- Identifier of the card definition the points are spent from, prefixed with `lcdef_`. required: - points - card_definition_id securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT X-App-Id: type: apiKey name: X-App-Id in: header X-App-Token: type: apiKey name: X-App-Token in: header ````