--- title: "List benefits" method: GET path: "/v2/loyalties/benefits" tags: ["Benefits"] --- # List benefits `GET /v2/loyalties/benefits` 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](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` integer, nullable - `order` union - string[] - '-created_at' | 'created_at' | 'name' | '-name' | '-type' | 'type' - `cursor` string, nullable - `filters` BenefitListFilters — Filters for the benefits list. Each field accepts a `conditions` object with at least one condition. Conditions of multiple fields are combined with the `junction`. - `junction` 'AND' | 'OR', nullable — How conditions of multiple fields are combined. Defaults to `AND`. - `id` BenefitIdFilterConditions — ID filter conditions for benefit IDs. At least one condition is required. - `conditions` object, required - `$is` union — Matches the exact benefit ID. Single value. - string - string[] - `$is_not` union — Excludes the exact benefit ID. Single value. - string - string[] - `$in` union — Matches any of the given benefit IDs. Up to 100 values. - string - string[] - `$not_in` union — Excludes all of the given benefit IDs. Up to 100 values. - string - string[] - `name` BenefitStringFilterConditions — String filter conditions. At least one condition is required. - `conditions` object, required - `$is` union — Matches the exact value. Single value. - string - string[] - `$is_not` union — Excludes the exact value. Single value. - string - string[] - `$contains` union — Matches values containing the given substring. Single value. - string - string[] - `$not_contain` union — Excludes values containing the given substring. Single value. - string - string[] - `$starts_with` union — Matches values starting with the given prefix. Single value. - string - string[] - `$ends_with` union — Matches values ending with the given suffix. Single value. - string - string[] - `$in` union — Matches any of the given values. Up to 10 values. - string - string[] - `$not_in` union — Excludes all of the given values. Up to 10 values. - string - string[] - `$has_value` string, nullable — Matches records where the field has a value. The condition value itself is ignored. - `$is_unknown` string, nullable — Matches records where the field has no value. The condition value itself is ignored. - `status` BenefitStatusFilterConditions — Enum filter conditions for benefit status. At least one condition is required. - `conditions` object, required - `$is` union — Matches the exact status. Single value. - 'ACTIVE' | 'DRAFT' - string[] - `$is_not` union — Excludes the exact status. Single value. - 'ACTIVE' | 'DRAFT' - string[] - `$in` union — Matches any of the given statuses. Up to 10 values. - 'ACTIVE' | 'DRAFT' - string[] - `$not_in` union — Excludes all of the given statuses. Up to 10 values. - 'ACTIVE' | 'DRAFT' - string[] - `type` BenefitTypeFilterConditions — Enum filter conditions for benefit type. At least one condition is required. - `conditions` object, required - `$is` union — Matches the exact type. Single value. - 'POINTS' | 'POINTS_PROPORTIONAL' | 'MATERIAL' | 'DIGITAL' - string[] - `$is_not` union — Excludes the exact type. Single value. - 'POINTS' | 'POINTS_PROPORTIONAL' | 'MATERIAL' | 'DIGITAL' - string[] - `$in` union — Matches any of the given types. Up to 10 values. - 'POINTS' | 'POINTS_PROPORTIONAL' | 'MATERIAL' | 'DIGITAL' - string[] - `$not_in` union — Excludes all of the given types. Up to 10 values. - 'POINTS' | 'POINTS_PROPORTIONAL' | 'MATERIAL' | 'DIGITAL' - string[] - `created_at` BenefitDateFilterConditions — Date filter conditions. At least one condition is required. - `conditions` object, required - `$before` union — Matches records created before the given date. ISO 8601 date-time string, single value. - string, date-time - string[] - `$after` union — Matches records created after the given date. ISO 8601 date-time string, single value. - string, date-time - string[] - `$is` union — Matches records created exactly the given number of days ago. Non-negative integer, single value. - string - string[] - `$more_than` union — Matches records created more than the given number of days ago. Non-negative integer, single value. - string - string[] - `$less_than` union — Matches records created less than the given number of days ago. Non-negative integer, single value. - string - string[] - `$has_value` string, nullable — Matches records where the field has a value. The condition value itself is ignored. - `$is_unknown` string, nullable — Matches records where the field has no value. The condition value itself is ignored. ## Response `200` Cursor-paginated list of benefits - BenefitListResponse — 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 — Stock configuration of the benefit. When `type` is `LIMITED` the `limited` object is required; when `type` is `UNLIMITED` the `limited` object must be omitted or null. - `type` 'UNLIMITED' | 'LIMITED', required — Whether the benefit has unlimited or limited stock. - `limited` BenefitStockLimited — Limited stock configuration. - `quantity` integer, required — Remaining stock quantity. - `points` BenefitPoints — 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`; the remaining source properties must be omitted or null. - `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` BenefitPointsProportionalEvery — 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` BenefitPointsProportionalEvery — 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` BenefitPointsProportionalMetadata — 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` BenefitPointsProportionalMetadata, 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` BenefitPointsProportionalMetadata, 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` BenefitPointsProportionalApplicableToProduct — Product reference. - … - `sku` BenefitPointsProportionalApplicableToSku — SKU reference. - … - `products_collection` BenefitPointsProportionalApplicableToProductsCollection — 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` BenefitPointsProportionalApplicableToProduct — Product reference. - … - `sku` BenefitPointsProportionalApplicableToSku — SKU reference. - … - `products_collection` BenefitPointsProportionalApplicableToProductsCollection — 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` BenefitPointsProportionalApplicableToProduct — Product reference. - … - `sku` BenefitPointsProportionalApplicableToSku — SKU reference. - … - `products_collection` BenefitPointsProportionalApplicableToProductsCollection — Products collection reference. - … - `material` BenefitMaterial — Material benefit - a physical product or SKU. Exactly one of `product` or `sku` is required, matching the `type`; the other must be omitted or null. - `type` 'PRODUCT' | 'SKU', required — Whether the benefit is a whole product or a specific SKU. - `product` BenefitMaterialProduct — Product reference for a material benefit. - `id` string, required — Product ID, prefixed with `prod_`. - `sku` BenefitMaterialSKU — 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`; the other must be omitted or null. 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` BenefitDigitalGiftVouchers — 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` BenefitDigitalDiscountCoupons — 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 — 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. - `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/f6f2f3388362/schema)