--- title: "List benefit activities" method: GET path: "/v2/loyalties/benefits/{benefitId}/activities" tags: ["Benefits"] --- # List benefit activities `GET /v2/loyalties/benefits/{benefitId}/activities` 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 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. ## Path parameters - `id` string, required ## Query parameters - `limit` integer, nullable - `order` union - string[] - 'created_at' | '-created_at' - `cursor` string, nullable - `filters` BenefitActivityListFilters — Filters for the benefit activities 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` BenefitActivityIdFilterConditions — ID filter conditions for benefit activity IDs. At least one condition is required. - `conditions` object, required - `$is` union — Matches the exact activity ID. Single value. - string - string[] - `$is_not` union — Excludes the exact activity ID. Single value. - string - string[] - `$in` union — Matches any of the given activity IDs. Up to 100 values. - string - string[] - `$not_in` union — Excludes all of the given activity IDs. Up to 100 values. - string - string[] - `type` BenefitActivityTypeFilterConditions — Enum filter conditions for benefit activity type. At least one condition is required. - `conditions` object, required - `$is` union — Matches the exact activity type. Single value. - 'vl.benefit.created' | 'vl.benefit.updated' | 'vl.benefit.deleted' | 'vl.benefit.activated' | 'vl.benefit.drafted' - string[] - `$is_not` union — Excludes the exact activity type. Single value. - 'vl.benefit.created' | 'vl.benefit.updated' | 'vl.benefit.deleted' | 'vl.benefit.activated' | 'vl.benefit.drafted' - string[] - `$in` union — Matches any of the given activity types. Up to 10 values. - 'vl.benefit.created' | 'vl.benefit.updated' | 'vl.benefit.deleted' | 'vl.benefit.activated' | 'vl.benefit.drafted' - string[] - `$not_in` union — Excludes all of the given activity types. Up to 10 values. - 'vl.benefit.created' | 'vl.benefit.updated' | 'vl.benefit.deleted' | 'vl.benefit.activated' | 'vl.benefit.drafted' - 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 benefit activities - BenefitActivityListResponse — 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 — 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. - … - `total_amount` BenefitPointsProportionalEvery — Ratio definition - `value` points for every `every` units. - … - `metadata` BenefitPointsProportionalMetadata — Metadata-based ratio definition - `value` points for every `every` units of the metadata property. - … - `customer` BenefitPointsProportionalCustomer — Customer-metadata-based proportional calculation. - `metadata` BenefitPointsProportionalMetadata, 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` BenefitPointsProportionalMetadata, 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`; 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`. - `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. - `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)