--- title: "List earning rules" method: GET path: "/v2/loyalties/earning-rules" tags: ["Earning Rules"] --- # List earning rules `GET /v2/loyalties/earning-rules` 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 earning rules. The same field cannot be used in both ascending and descending order at once (e.g. `order=name&order=-name` is rejected). Default order is `-created_at`; `id` is always appended as a tie-breaker. ## Query parameters - `limit` integer - `order` union - '-created_at' | 'created_at' | 'name' | '-name' - string[] - `cursor` string - `filters` EarningRuleListFilters — Filters for listing earning rules. Each field carries a required `conditions` object; condition values may be passed as a single string or as an array. Conditions not allowed for the field type are rejected. - `junction` 'AND' | 'OR' — How multiple field filters are combined. Defaults to AND behaviour. Nullable. - `id` object — ID filter. Allowed conditions: `$is`, `$is_not` (single value), `$in`, `$not_in` (up to 100 values). Values must match `^lern_[a-f0-9]+$`. Nullable. - `conditions` object, required - `$is` union — Exactly matches the value (single value). - string - string[] - `$is_not` union — Does not match the value (single value). - string - string[] - `$in` union — Matches any of the values (up to 100). - string - string[] - `$not_in` union — Matches none of the values (up to 100). - string - string[] - `name` EarningRuleStringFilterConditions — String field filter conditions. `$is`, `$is_not`, `$contains`, `$not_contain`, `$starts_with` and `$ends_with` take a single value (string or one-element array); `$in` and `$not_in` take up to 10 values; `$has_value` and `$is_unknown` are presence checks (value is ignored). - `conditions` object, required - `$is` union — Exactly matches the value. - string - string[] - `$is_not` union — Does not match the value. - string - string[] - `$contains` union — Contains the substring. - string - string[] - `$not_contain` union — Does not contain the substring. - string - string[] - `$starts_with` union — Starts with the prefix. - string - string[] - `$ends_with` union — Ends with the suffix. - string - string[] - `$in` union — Matches any of the values (up to 10). - string - string[] - `$not_in` union — Matches none of the values (up to 10). - string - string[] - `$has_value` string — Field has a value (presence check). - `$is_unknown` string — Field has no value (absence check). - `status` object — Status filter (enum type). Allowed conditions: `$is`, `$is_not` (single value), `$in`, `$not_in` (up to 10 values). Allowed values: `ACTIVE`, `INACTIVE`, `DRAFT`. Nullable. - `conditions` object, required - `$is` union — Exactly matches the value (single value). - 'ACTIVE' | 'INACTIVE' | 'DRAFT' - string[] - `$is_not` union — Does not match the value (single value). - 'ACTIVE' | 'INACTIVE' | 'DRAFT' - string[] - `$in` union — Matches any of the values (up to 10). - 'ACTIVE' | 'INACTIVE' | 'DRAFT' - string[] - `$not_in` union — Matches none of the values (up to 10). - 'ACTIVE' | 'INACTIVE' | 'DRAFT' - string[] - `created_at` EarningRuleDateFilterConditions — Date field filter conditions. `$before` and `$after` take a date string; `$is`, `$more_than` and `$less_than` take a non-negative integer number of days (relative comparison); `$has_value` and `$is_unknown` are presence checks. - `conditions` object, required - `$before` union — Before the given date (single date string). - string - string[] - `$after` union — After the given date (single date string). - string - string[] - `$is` union — Exactly N days ago (non-negative integer). - string - string[] - `$more_than` union — More than N days ago (non-negative integer). - string - string[] - `$less_than` union — Less than N days ago (non-negative integer). - string - string[] - `$has_value` string — Field has a value (presence check). - `$is_unknown` string — Field has no value (absence check). ## Response `200` Paginated list of earning rules - EarningRuleListResponse — Cursor-paginated list of earning rules. - `data` EarningRuleResponse[] — Earning rules on the current page. - `id` string — Earning rule ID (`lern_...`). - `name` string — Earning rule name. - `status` 'DRAFT' | 'ACTIVE' | 'INACTIVE' — Current status. `DELETED` also exists internally but deleted rules are excluded from API reads. - `earnings` EarningRuleEarningResponse[] — Earning definitions of the rule. - `id` string — Earning item ID (`lernei_...`). - `name` unknown - `rules` EarningRuleRulesGroup — Group of rule definitions combined by a logical formula. Besides `logic`, only positive-integer keys are allowed (property names must match `^[1-9]\d*$`), each referencing a rule definition. The `logic` value is a logical expression referencing the numbered rules, e.g. `"1 and 2"` or `"1 and (2 or 3)"`. At least one numbered rule is required (`minProperties: 2` including `logic`). - `logic` string, required — Logical expression combining the numbered rule definitions, e.g. `"1 and 2"`. - `tier_rules` EarningRuleTierRules — Tier requirements for an earning. With `NO_REQUIREMENTS`, `any_of` must be null/absent. With `ANY_OF`, `any_of` is required (at least one entry) and the member must be in any of the listed tiers to earn. - `type` 'NO_REQUIREMENTS' | 'ANY_OF', required — Tier requirement type. - `any_of` EarningRuleTierRulesAnyOfEntry[] — Tier structure/tier combinations, any of which satisfies the requirement. Nullable. - `tier_structure_id` string, required — Tier structure ID (`lts_...`). - `tier_ids` string[], required — Qualifying tier IDs (`lt_...`). - `effects` EarningRuleEffect[] — Effects applied when the rules match. - `type` 'POINTS' | 'POINTS_PROPORTIONAL' | 'BENEFIT', required — Effect type. - `points` EarningRuleEffectPoints — Fixed points effect - awards a fixed number of points to a card definition. - `value` integer, required — Fixed number of points to award. - `card_definition_id` string, required — Card definition ID (`lcdef_...`) the points are awarded to. - `points_expiration` EarningRuleEffectPointsExpiration — Points expiration override. Depending on `type`, exactly one of `rolling_expiration`, `calendar_expiration` or `sliding_expiration` is required; for `NO_EXPIRATION` all three must be null/absent. - `type` 'NO_EXPIRATION' | 'ROLLING_EXPIRATION' | 'CALENDAR_EXPIRATION' | 'SLIDING_EXPIRATION', required — Points expiration type. - `rolling_expiration` EarningRuleEffectPointsExpirationRollingExpiration — Rolling expiration - points expire a fixed period after earning. - … - `calendar_expiration` EarningRuleEffectPointsExpirationCalendarExpiration — Calendar expiration - points expire on fixed calendar dates (1 to 20 dates). - … - `sliding_expiration` EarningRuleEffectPointsExpirationSlidingExpiration — Sliding expiration - points expire after a period of member inactivity. At least one of `earning_activity`, `spending_activity` or `custom_activity` must be `true`. When `custom_activity` is `true`, `custom_activity_types` is required (1-10 unique items). - … - `points_proportional` EarningRuleEffectPointsProportional — Proportional points effect - awards points using an "every X gives Y points" formula. Depending on `calculation_type`, one specific configuration object is required and the others must be null/absent: - `PRE_DISCOUNT_ORDER_AMOUNT`: requires `order.amount` - `POST_DISCOUNT_ORDER_AMOUNT`: requires `order.total_amount` - `ORDER_METADATA_VALUE`: requires `order.metadata` - `CUSTOMER_METADATA_VALUE`: requires `customer.metadata` - `CUSTOM_EVENT_METADATA_VALUE`: requires `custom_event.metadata` - `PRE_DISCOUNT_ORDER_ITEMS_AMOUNT`: requires `order_items.amount` - `POST_DISCOUNT_ORDER_ITEMS_AMOUNT`: requires `order_items.subtotal_amount` - `ORDER_ITEMS_QUANTITY`: requires `order_items.quantity` The trigger further restricts allowed calculation types: `customer.order.paid` allows all order/order-items types plus `CUSTOMER_METADATA_VALUE`; `customer.custom_event` allows `CUSTOMER_METADATA_VALUE` and `CUSTOM_EVENT_METADATA_VALUE`; `customer.segment.entered` allows only `CUSTOMER_METADATA_VALUE`. - `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 proportional points are calculated. - `card_definition_id` string, required — Card definition ID (`lcdef_...`) the points are awarded to. - `points_expiration` EarningRuleEffectPointsExpiration — Points expiration override. Depending on `type`, exactly one of `rolling_expiration`, `calendar_expiration` or `sliding_expiration` is required; for `NO_EXPIRATION` all three must be null/absent. - `type` 'NO_EXPIRATION' | 'ROLLING_EXPIRATION' | 'CALENDAR_EXPIRATION' | 'SLIDING_EXPIRATION', required — Points expiration type. - `rolling_expiration` EarningRuleEffectPointsExpirationRollingExpiration — Rolling expiration - points expire a fixed period after earning. - … - `calendar_expiration` EarningRuleEffectPointsExpirationCalendarExpiration — Calendar expiration - points expire on fixed calendar dates (1 to 20 dates). - … - `sliding_expiration` EarningRuleEffectPointsExpirationSlidingExpiration — Sliding expiration - points expire after a period of member inactivity. At least one of `earning_activity`, `spending_activity` or `custom_activity` must be `true`. When `custom_activity` is `true`, `custom_activity_types` is required (1-10 unique items). - … - `order` EarningRulePointsProportionalOrder — Order-based proportional calculation configuration. `amount` is used by `PRE_DISCOUNT_ORDER_AMOUNT`, `total_amount` by `POST_DISCOUNT_ORDER_AMOUNT` and `metadata` by `ORDER_METADATA_VALUE`. - `amount` EarningRulePointsProportionalEvery — "Every X gives Y points" formula based on an amount. - … - `total_amount` EarningRulePointsProportionalEvery — "Every X gives Y points" formula based on an amount. - … - `metadata` EarningRulePointsProportionalMetadata — "Every X gives Y points" formula based on a numeric metadata property. - … - `customer` EarningRulePointsProportionalCustomer — Customer-based proportional calculation configuration (`CUSTOMER_METADATA_VALUE`). - `metadata` EarningRulePointsProportionalMetadata, required — "Every X gives Y points" formula based on a numeric metadata property. - … - `custom_event` EarningRulePointsProportionalCustomEvent — Custom event based proportional calculation configuration (`CUSTOM_EVENT_METADATA_VALUE`). - `metadata` EarningRulePointsProportionalMetadata, required — "Every X gives Y points" formula based on a numeric metadata property. - … - `order_items` EarningRulePointsProportionalOrderItems — Order items based proportional calculation configuration. `amount` is used by `PRE_DISCOUNT_ORDER_ITEMS_AMOUNT`, `subtotal_amount` by `POST_DISCOUNT_ORDER_ITEMS_AMOUNT` and `quantity` by `ORDER_ITEMS_QUANTITY`. - `amount` EarningRulePointsProportionalOrderItemsCalculation — Order items based calculation - "every X gives Y points" applied to items matching the `applicable_to` criteria. - … - `subtotal_amount` EarningRulePointsProportionalOrderItemsCalculation — Order items based calculation - "every X gives Y points" applied to items matching the `applicable_to` criteria. - … - `quantity` EarningRulePointsProportionalOrderItemsCalculation — Order items based calculation - "every X gives Y points" applied to items matching the `applicable_to` criteria. - … - `benefit` EarningRuleEffectBenefit — Benefit effect - grants a predefined benefit. - `id` string, required — Benefit ID (`lben_...`). - `trigger` EarningRuleTrigger — Event that triggers the earning rule. Depending on `event`, either `custom_event` or `segment` is required and the other trigger contexts must be null/absent. - `event` 'customer.order.paid' | 'customer.custom_event' | 'customer.segment.entered', required — Triggering event type. - `custom_event` EarningRuleTriggerCustomEvent — Custom event trigger configuration. - `schema_id` string, required — Custom event schema ID (`ms_...`). - `segment` EarningRuleTriggerSegment — Segment trigger configuration. - `id` string, required — Segment ID (`seg_...`). - `error` EarningRuleError — Custom error message configuration. - `message` string, required — Error message shown when validation fails. - `validity_hours` EarningRuleValidityHours — Hours during which the earning rule is active. With `ANY_TIME`, `daily` must be null/absent. With `DAILY`, `daily` is required (at least one entry). - `type` 'DAILY' | 'ANY_TIME', required — Validity hours type. - `daily` EarningRuleValidityDailyHours[] — Daily validity windows. Nullable. - `days_of_week` integer[], required — Days of week (0 = Sunday ... 6 = Saturday). Items must be unique. - `start_time` string, required — Window start time in `HH:mm` format. - `end_time` string, required — Window end time in `HH:mm` format. - `start_date` string, date-time — Date-time from which the rule is active. Nullable. - `end_date` string, date-time — Date-time until which the rule is active. Nullable. - `trigger_limits` EarningRuleTriggerLimits — Cooldown and frequency limits applied to the earning rule trigger. - `cooldown` EarningRuleTriggerLimitsCooldown — Cooldown between consecutive triggers per member. With `NO_COOLDOWN`, `fixed_cooldown` must be null/absent. With `FIXED_COOLDOWN`, `fixed_cooldown` is required. - `type` 'NO_COOLDOWN' | 'FIXED_COOLDOWN', required — Cooldown type. - `fixed_cooldown` EarningRuleTriggerLimitsCooldownFixedCooldown — Fixed cooldown period configuration. - `period` EarningRuleTriggerLimitsCooldownFixedCooldownPeriod, required — Cooldown period. The maximum `value` depends on `unit`: `HOUR` - 24, `DAY` - 90, `WEEK` - 52, `MONTH` - 12, `YEAR` - 1. - `value` integer, required — Period length. Maximum depends on `unit`: 24 for HOUR, 90 for DAY, 52 for WEEK, 12 for MONTH, 1 for YEAR. - `unit` 'HOUR' | 'DAY' | 'WEEK' | 'MONTH' | 'YEAR', required — Period unit. - `frequency` EarningRuleTriggerLimitsFrequency — Frequency limit for triggers per member. With `NO_LIMIT`, `limits` must be null or an empty array. With `LIMITED`, `limits` is required and must contain exactly one limit. - `type` 'NO_LIMIT' | 'LIMITED', required — Frequency limit type. - `limits` EarningRuleTriggerLimitsFrequencyLimit[] — Frequency limits (at most one). Nullable. - `type` 'TIME_BASED', required — Frequency limit variant. - `period` EarningRuleTriggerLimitsFrequencyLimitTimeBasedPeriod, required — Time-based frequency limit period. Currently only `CURRENT_PERIOD` is supported; when selected, `current_period` is required. - `type` 'CURRENT_PERIOD', required — Period type. - `current_period` EarningRuleTriggerLimitsFrequencyLimitTimeBasedCurrentPeriod — Current calendar period unit for the frequency limit. - … - `triggers` EarningRuleTriggerLimitsFrequencyLimitTimeBasedTriggers, required — Maximum number of triggers allowed within the period. - `max` integer, required — Maximum number of triggers per period. - `metadata` EarningRuleMetadata — Arbitrary key-value metadata; any JSON object is accepted. - `created_at` string, date-time — Creation timestamp (ISO 8601). - `updated_at` string, date-time — Last update timestamp (ISO 8601). Null when never updated. - `object` string — Object type marker. Always `earning_rule`. - `cursor` EarningRuleListCursor — Pagination cursor. Null when there are no more results. - `next` string — Cursor ID to pass as the `cursor` query parameter to fetch the next page. - `expires_at` string, date-time — Cursor expiration timestamp. - `object` string — Object type marker. 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-api-async-actions.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-api-async-actions/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-api-async-actions/versions/4982266e0494/schema)