--- title: "List benefit activities" method: GET path: "/v2/loyalties/benefits/{benefitId}/activities" tags: ["Benefits"] --- # List benefit activities `GET /v2/loyalties/benefits/{benefitId}/activities` ## Request - Base URL: `https://api.voucherify.io` - URL: `https://api.voucherify.io/v2/loyalties/benefits/{benefitId}/activities` - 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 activities recorded for the benefit (created, updated, deleted, activated, drafted). Returns `404` when the benefit does not exist. Supports filtering by activity `id`, `type`, and `created_at`, ordering by `created_at` (default `-created_at`), and cursor-based pagination. ## Query parameters - `limit` union - number - string - `order` union - string[] - 'created_at' | '-created_at' - `cursor` string, nullable - `filters` LoyaltiesBenefitsActivitiesListRequestQuery: Request query schema for **GET** `/v2/loyalties/benefits/{benefitId}/activities`. - `junction` 'AND' | 'OR', nullable: Joins the field filters. Allowed values are `AND` and `OR`. Defaults to `AND`. - `id` LoyaltiesBenefitsActivitiesListRequestQueryId: ID conditions. Format `laben_[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 `laben_[a-f0-9]+`. - string - string[] - `$is_not` union: Excludes one value. A string or a one-element array. Format `laben_[a-f0-9]+`. - string - string[] - `$in` union: Matches any of the values. A string or an array of 1 to 100 values. Format `laben_[a-f0-9]+`. - string - string[] - `$not_in` union: Excludes any of the values. A string or an array of 1 to 100 values. Format `laben_[a-f0-9]+`. - string - string[] - `type` LoyaltiesBenefitsActivitiesListRequestQueryType: Enum conditions. At least one condition is required. - `conditions` object, required - `$is` union: Matches one value. A string or a one-element array. - 'vl.benefit.created' | 'vl.benefit.updated' | 'vl.benefit.deleted' | 'vl.benefit.activated' | 'vl.benefit.drafted' - string[] - `$is_not` union: Excludes one value. A string or a one-element array. - 'vl.benefit.created' | 'vl.benefit.updated' | 'vl.benefit.deleted' | 'vl.benefit.activated' | 'vl.benefit.drafted' - string[] - `$in` union: Matches any of the values. A string or an array of 1 to 10 values. - 'vl.benefit.created' | 'vl.benefit.updated' | 'vl.benefit.deleted' | 'vl.benefit.activated' | 'vl.benefit.drafted' - string[] - `$not_in` union: Excludes any of the values. A string or an array of 1 to 10 values. - 'vl.benefit.created' | 'vl.benefit.updated' | 'vl.benefit.deleted' | 'vl.benefit.activated' | 'vl.benefit.drafted' - 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 benefit activities - V2LoyaltiesBenefitsActivitiesListResponseBody: Cursor-paginated list of benefit activities. - `data` BenefitActivity[], required: Activities matching the query, in the requested order. - `id` string, required: Unique activity ID, prefixed with `laben_`. - `type` 'vl.benefit.created' | 'vl.benefit.updated' | 'vl.benefit.deleted' | 'vl.benefit.activated' | 'vl.benefit.drafted', required: Type of the recorded activity. - `data` BenefitActivityData, required: Activity payload containing a snapshot of the benefit at the time of the activity. - `benefit` Benefit, required: A benefit object. Exactly one type-specific configuration object (`points`, `points_proportional`, `material`, or `digital`) is present, matching the `type`; the others are omitted. - `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. - … - `total_amount` LoyaltyV2ActivityBenefitPointsProportionalEvery: Ratio definition - `value` points for every `every` units. - … - `metadata` LoyaltyV2ActivityBenefitPointsProportionalMetadata: Metadata-based ratio definition - `value` points for every `every` units of the metadata property. - … - `customer` BenefitPointsProportionalCustomer: Customer-metadata-based proportional calculation. - `metadata` LoyaltyV2ActivityBenefitPointsProportionalMetadata, required: Metadata-based ratio definition - `value` points for every `every` units of the metadata property. - … - `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. - … - `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. - … - `subtotal_amount` BenefitPointsProportionalOrderItemsCalculation: Order-items ratio definition with the list of applicable products/SKUs/collections. - … - `quantity` BenefitPointsProportionalOrderItemsCalculation: Order-items ratio definition with the list of applicable products/SKUs/collections. - … - `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`. - `created_at` string, date-time, required: Timestamp of when the activity was recorded, in ISO 8601 format. - `group_id` string: ID grouping activities recorded within the same operation. - `source` BenefitActivitySource: Origin of the activity. - `channel` 'USER_PORTAL' | 'API' | 'CLIENT_API' | 'INTERNAL': Channel the activity originated from. - `user` BenefitActivitySourceUser: User who triggered the activity. - `id` string: User ID. - `api_key` BenefitActivitySourceApiKey: API key used to trigger the activity. - `name` string: Name of the API key. - `app_id` string: Application ID of the API key. - `client_app_id` string: Client application ID (for client-side API keys). - `benefit_id` string, required: ID of the benefit the activity relates to. - `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, 1 warning, 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 - …4 more - **2026-10-13** (v2) `f95b50556c93`: 3 breaking, 5 info - added the new path request parameter `benefitId` - 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/BenefitActivityListResponse` from the response body `allOf` list for the response status `200` - …4 more - **2026-10-13** (v2) `9905dfce1d1e`: 4 breaking, 1 warning, 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 - …4 more - …earlier changes not shown [Operation history](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/changes/v2/loyalties/benefits/:benefitId/activities/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)