--- title: "List benefits" method: GET path: "/v2/loyalties/benefits" tags: ["Benefits"] --- # List benefits `GET /v2/loyalties/benefits` 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` 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/versions/69be73b5cff0/schema)