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