--- title: "List benefits" method: GET path: "/v2/loyalties/benefits" tags: ["Benefits"] --- # List benefits `GET /v2/loyalties/benefits` ## Request - Base URL: `https://api.voucherify.io` - URL: `https://api.voucherify.io/v2/loyalties/benefits` - Auth: one of: - API key in header `X-App-Id` and API key in header `X-App-Token` - HTTP bearer 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 benefits. Supports filtering by `id`, `name`, `status`, `type`, and `created_at`, ordering by `created_at`, `name`, and `type` (prefix with `-` for descending), and cursor-based pagination. Deleted benefits are excluded. Multiple filters are combined with the `junction` (`AND` by default). The same field cannot be ordered both ascending and descending at the same time. ## Query parameters - `limit` union - number - string - `order` union - string[] - '-created_at' | 'created_at' | 'name' | '-name' | '-type' | 'type' - `cursor` string, nullable - `filters` LoyaltiesBenefitsListRequestQuery: Request query schema for **GET** `/v2/loyalties/benefits`. - `junction` 'AND' | 'OR', nullable: Joins the field filters. Allowed values are `AND` and `OR`. Defaults to `AND`. - `id` LoyaltiesBenefitsListRequestQueryId: ID conditions. Format `lben_[a-f0-9]+`. At least one condition is required. - `conditions` object, required - `$is` union: Matches one value. A string or a one-element array. Format `lben_[a-f0-9]+`. - string - string[] - `$is_not` union: Excludes one value. A string or a one-element array. Format `lben_[a-f0-9]+`. - string - string[] - `$in` union: Matches any of the values. A string or an array of 1 to 100 values. Format `lben_[a-f0-9]+`. - string - string[] - `$not_in` union: Excludes any of the values. A string or an array of 1 to 100 values. Format `lben_[a-f0-9]+`. - string - string[] - `name` LoyaltiesBenefitsListRequestQueryName: String conditions. At least one condition is required. - `conditions` object, required - `$is` union: Matches one value. A string or a one-element array. - string - string[] - `$is_not` union: Excludes one value. A string or a one-element array. - string - string[] - `$contains` union: Matches when the value contains the substring. A string or a one-element array. - string - string[] - `$not_contain` union: Excludes values that contain the substring. A string or a one-element array. - string - string[] - `$starts_with` union: Matches when the value starts with the prefix. A string or a one-element array. - string - string[] - `$ends_with` union: Matches when the value ends with the suffix. A string or a one-element array. - string - string[] - `$in` union: Matches any of the values. A string or an array of 1 to 10 values. - string - string[] - `$not_in` union: Excludes any of the values. A string or an array of 1 to 10 values. - string - string[] - `$has_value` string, nullable: Matches when the field is set. The condition value is ignored. - `$is_unknown` string, nullable: Matches when the field is not set. The condition value is ignored. - `status` LoyaltiesBenefitsListRequestQueryStatus: Enum conditions. At least one condition is required. - `conditions` object, required - `$is` union: Matches one value. A string or a one-element array. - 'ACTIVE' | 'DRAFT' - string[] - `$is_not` union: Excludes one value. A string or a one-element array. - 'ACTIVE' | 'DRAFT' - string[] - `$in` union: Matches any of the values. A string or an array of 1 to 10 values. - 'ACTIVE' | 'DRAFT' - string[] - `$not_in` union: Excludes any of the values. A string or an array of 1 to 10 values. - 'ACTIVE' | 'DRAFT' - string[] - `type` LoyaltiesBenefitsListRequestQueryType: Enum conditions. At least one condition is required. - `conditions` object, required - `$is` union: Matches one value. A string or a one-element array. - 'POINTS' | 'POINTS_PROPORTIONAL' | 'MATERIAL' | 'DIGITAL' - string[] - `$is_not` union: Excludes one value. A string or a one-element array. - 'POINTS' | 'POINTS_PROPORTIONAL' | 'MATERIAL' | 'DIGITAL' - string[] - `$in` union: Matches any of the values. A string or an array of 1 to 10 values. - 'POINTS' | 'POINTS_PROPORTIONAL' | 'MATERIAL' | 'DIGITAL' - string[] - `$not_in` union: Excludes any of the values. A string or an array of 1 to 10 values. - 'POINTS' | 'POINTS_PROPORTIONAL' | 'MATERIAL' | 'DIGITAL' - string[] - `created_at` BenefitDateFilterConditions: Date conditions. At least one condition is required. - `conditions` object, required - `$before` union: Matches dates before the given value. An ISO 8601 date-time, as a string or a one-element array. - string, date-time - string[] - `$after` union: Matches dates after the given value. An ISO 8601 date-time, as a string or a one-element array. - string, date-time - string[] - `$is` union: Matches a date exactly the given number of days ago. A non-negative integer, as a string or a one-element array. - string - string[] - `$more_than` union: Matches dates more than the given number of days ago. A non-negative integer, as a string or a one-element array. - string - string[] - `$less_than` union: Matches dates less than the given number of days ago. A non-negative integer, as a string or a one-element array. - string - string[] - `$has_value` string, nullable: Matches when the field is set. The condition value is ignored. - `$is_unknown` string, nullable: Matches when the field is not set. The condition value is ignored. ## Response `200` Cursor-paginated list of benefits - V2LoyaltiesBenefitsListResponseBody: Cursor-paginated list of benefits. - `data` Benefit[], required: Benefits matching the query, in the requested order. - `id` string, required: Unique benefit ID, prefixed with `lben_`. - `name` string, required: Benefit name, unique within the project. - `type` 'POINTS' | 'POINTS_PROPORTIONAL' | 'MATERIAL' | 'DIGITAL', required: Benefit type. - `status` 'DRAFT' | 'ACTIVE' | 'DELETED', required: Current benefit status. `DELETED` appears only in the response of the delete endpoint and in activity snapshots. - `stock` BenefitStock, required: Stock configuration of the benefit. When `type` is `LIMITED`, the `limited` object is required. When `type` is `UNLIMITED`, requests may omit `limited` or set it to `null`; responses omit it. - `type` 'UNLIMITED' | 'LIMITED', required: Whether the benefit has unlimited or limited stock. - `limited` LoyaltyV2ActivityBenefitStockLimited: Limited stock configuration. - `quantity` integer, required: Available Remaining stock quantity. For responses, updates with each benefit purchase. - `points` LoyaltyV2ActivityBenefitPoints: Fixed points effect - adds a fixed amount of points to a card of the given card definition. - `value` integer, required: Number of points to add. - `card_definition_id` string, required: ID of the card definition whose cards receive the points. The card definition must exist and be `ACTIVE`. - `points_proportional` BenefitPointsProportional: Proportional points effect - points are calculated from an order amount, order items, or a metadata property. Exactly one calculation source object (`order`, `customer`, `custom_event`, or `order_items`) is required, determined by `calculation_type`. In requests, the remaining source properties may be omitted or set to `null`. In responses, they are omitted. - `calculation_type` 'PRE_DISCOUNT_ORDER_AMOUNT' | 'POST_DISCOUNT_ORDER_AMOUNT' | 'PRE_DISCOUNT_ORDER_ITEMS_AMOUNT' | 'POST_DISCOUNT_ORDER_ITEMS_AMOUNT' | 'ORDER_ITEMS_QUANTITY' | 'ORDER_METADATA_VALUE' | 'CUSTOMER_METADATA_VALUE' | 'CUSTOM_EVENT_METADATA_VALUE', required: How the points are calculated: - `PRE_DISCOUNT_ORDER_AMOUNT` - points per every specified order amount before discounts (requires `order.amount`) - `POST_DISCOUNT_ORDER_AMOUNT` - points per every specified order amount after discounts (requires `order.total_amount`) - `PRE_DISCOUNT_ORDER_ITEMS_AMOUNT` - points per every specified amount spent on selected products before discounts (requires `order_items.amount`) - `POST_DISCOUNT_ORDER_ITEMS_AMOUNT` - points per every specified amount spent on selected products after discounts (requires `order_items.subtotal_amount`) - `ORDER_ITEMS_QUANTITY` - points per every specified quantity of selected products, excluding free items (requires `order_items.quantity`) - `ORDER_METADATA_VALUE` - points per every specified value in the order metadata (requires `order.metadata`) - `CUSTOMER_METADATA_VALUE` - points per every specified value in the customer metadata (requires `customer.metadata`) - `CUSTOM_EVENT_METADATA_VALUE` - points per every specified value in the custom event metadata (requires `custom_event.metadata`) - `card_definition_id` string, required: ID of the card definition whose cards receive the points. The card definition must exist and be ACTIVE. - `order` BenefitPointsProportionalOrder: Order-based proportional calculation. Provide the property matching the `calculation_type`. - `amount` LoyaltyV2ActivityBenefitPointsProportionalEvery: Ratio definition - `value` points for every `every` units. - `every` integer, required: Unit step (e.g. order amount in cents) for which `value` points are granted. - `value` number, required: Number of points granted per `every` units. - `total_amount` LoyaltyV2ActivityBenefitPointsProportionalEvery: Ratio definition - `value` points for every `every` units. - `every` integer, required: Unit step (e.g. order amount in cents) for which `value` points are granted. - `value` number, required: Number of points granted per `every` units. - `metadata` LoyaltyV2ActivityBenefitPointsProportionalMetadata: Metadata-based ratio definition - `value` points for every `every` units of the metadata property. - `every` integer, required: Unit step of the metadata property value for which `value` points are granted. - `value` number, required: Number of points granted per `every` units. - `property` string, required: Name of the metadata property used for the calculation. - `customer` BenefitPointsProportionalCustomer: Customer-metadata-based proportional calculation. - `metadata` LoyaltyV2ActivityBenefitPointsProportionalMetadata, required: Metadata-based ratio definition - `value` points for every `every` units of the metadata property. - `every` integer, required: Unit step of the metadata property value for which `value` points are granted. - `value` number, required: Number of points granted per `every` units. - `property` string, required: Name of the metadata property used for the calculation. - `custom_event` BenefitPointsProportionalCustomEvent: Custom-event-metadata-based proportional calculation. - `metadata` LoyaltyV2ActivityBenefitPointsProportionalMetadata, required: Metadata-based ratio definition - `value` points for every `every` units of the metadata property. - `every` integer, required: Unit step of the metadata property value for which `value` points are granted. - `value` number, required: Number of points granted per `every` units. - `property` string, required: Name of the metadata property used for the calculation. - `order_items` BenefitPointsProportionalOrderItems: Order-items-based proportional calculation. Provide the property matching the `calculation_type`. - `amount` BenefitPointsProportionalOrderItemsCalculation: Order-items ratio definition with the list of applicable products/SKUs/collections. - `every` integer, required: Unit step (amount or quantity) for which `value` points are granted. - `value` number, required: Number of points granted per `every` units. - `applicable_to` BenefitPointsProportionalApplicableTo[], required: Products, SKUs, or product collections the calculation applies to. - `type` 'product' | 'sku' | 'products_collection', required: Type of the referenced object. - `product` LoyaltyV2ActivityBenefitPointsProportionalApplicableToProduct: Product reference. - … - `sku` LoyaltyV2ActivityBenefitPointsProportionalApplicableToSku: SKU reference. - … - `products_collection` LoyaltyV2ActivityBenefitPointsProportionalApplicableToProductsCollection: Products collection reference. - … - `subtotal_amount` BenefitPointsProportionalOrderItemsCalculation: Order-items ratio definition with the list of applicable products/SKUs/collections. - `every` integer, required: Unit step (amount or quantity) for which `value` points are granted. - `value` number, required: Number of points granted per `every` units. - `applicable_to` BenefitPointsProportionalApplicableTo[], required: Products, SKUs, or product collections the calculation applies to. - `type` 'product' | 'sku' | 'products_collection', required: Type of the referenced object. - `product` LoyaltyV2ActivityBenefitPointsProportionalApplicableToProduct: Product reference. - … - `sku` LoyaltyV2ActivityBenefitPointsProportionalApplicableToSku: SKU reference. - … - `products_collection` LoyaltyV2ActivityBenefitPointsProportionalApplicableToProductsCollection: Products collection reference. - … - `quantity` BenefitPointsProportionalOrderItemsCalculation: Order-items ratio definition with the list of applicable products/SKUs/collections. - `every` integer, required: Unit step (amount or quantity) for which `value` points are granted. - `value` number, required: Number of points granted per `every` units. - `applicable_to` BenefitPointsProportionalApplicableTo[], required: Products, SKUs, or product collections the calculation applies to. - `type` 'product' | 'sku' | 'products_collection', required: Type of the referenced object. - `product` LoyaltyV2ActivityBenefitPointsProportionalApplicableToProduct: Product reference. - … - `sku` LoyaltyV2ActivityBenefitPointsProportionalApplicableToSku: SKU reference. - … - `products_collection` LoyaltyV2ActivityBenefitPointsProportionalApplicableToProductsCollection: Products collection reference. - … - `material` BenefitMaterial: Material benefit - a physical product or SKU. Exactly one of `product` or `sku` is required, matching the `type`. In requests, the other property may be omitted or set to `null`. In responses, it is omitted. - `type` 'PRODUCT' | 'SKU', required: Whether the benefit is a whole product or a specific SKU. - `product` LoyaltyV2ActivityBenefitMaterialProduct: Product reference for a material benefit. - `id` string, required: Product ID, prefixed with `prod_`. - `sku` LoyaltyV2ActivityBenefitMaterialSKU: SKU reference for a material benefit. - `product_id` string, required: ID of the product the SKU belongs to, prefixed with `prod_`. - `id` string, required: SKU ID, prefixed with `sku_`. - `digital` BenefitDigital: Digital benefit - a reward sourced from a Voucherify campaign. Exactly one of `gift_vouchers` or `discount_coupons` is required, matching the `type`. In requests, the other property may be omitted or set to `null`. In responses, it is omitted. The referenced campaign must exist and its campaign type must match the benefit's digital type. - `type` 'GIFT_VOUCHERS' | 'DISCOUNT_COUPONS', required: Type of the digital reward. - `gift_vouchers` LoyaltyV2ActivityBenefitDigitalGiftVouchers: Gift vouchers digital benefit configuration. - `campaign_id` string, required: ID of the `GIFT_VOUCHERS` campaign the vouchers are sourced from, prefixed with `camp_`. - `balance` number, required: Balance loaded onto the gift voucher. - `discount_coupons` LoyaltyV2ActivityBenefitDigitalDiscountCoupons: Discount coupons digital benefit configuration. - `campaign_id` string, required: ID of the `DISCOUNT_COUPONS` campaign the coupons are sourced from, prefixed with `camp_`. - `created_at` string, date-time, required: Timestamp of when the benefit was created, in ISO 8601 format. - `updated_at` string, date-time, nullable, required: Timestamp of the last update, in ISO 8601 format. `null` when the benefit was never updated. - `object` 'benefit', required: Type of the object. Always `benefit`. - `cursor` BenefitListCursor, required: Pagination cursor pointing to the next page of results. - `next` string, required: Cursor ID to pass as the `cursor` query parameter to fetch the next page. - `expires_at` string, date-time: Timestamp after which the cursor expires. - `object` 'list', required: Type of the object. 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. - `500`: Internal server error. ## Changes - **2026-10-14** (v2) `ec801ade260d`: 4 breaking, 3 info - for the `query` request parameter `limit`, the type changed from `integer, null` to `number, string, null` - removed the required property `cursor` from the response with the `200` status - removed the required property `data` from the response with the `200` status - removed the required property `object` from the response with the `200` status - …3 more - **2026-10-13** (v2) `f95b50556c93`: 2 breaking, 5 info - for the `query` request parameter `filters`, the type changed from no type to `object` - for the `query` request parameter `limit`, the type changed from `number, string, null` to `integer, null` - removed `#/components/schemas/BenefitListResponse` from the response body `allOf` list for the response status `200` - added the non-success response with the status `409` - …3 more - **2026-10-13** (v2) `9905dfce1d1e`: 4 breaking, 3 info - for the `query` request parameter `limit`, the type changed from `integer, null` to `number, string, null` - removed the required property `cursor` from the response with the `200` status - removed the required property `data` from the response with the `200` status - removed the required property `object` from the response with the `200` status - …3 more - …earlier changes not shown [Operation history](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/changes/v2/loyalties/benefits/get.md) --- [API](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api.md) - [All operations](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/revisions/e0d9f2d2532f?raw)