--- title: "Activate earning rule" method: POST path: "/v2/loyalties/earning-rules/{earningRuleId}/activate" tags: ["Earning Rules"] --- # Activate earning rule `POST /v2/loyalties/earning-rules/{earningRuleId}/activate` 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. Moves the earning rule to `ACTIVE` status. No request body. Allowed transitions: `DRAFT -> ACTIVE`, `INACTIVE -> ACTIVE`. Invalid transitions are rejected with a conflict error. ## Path parameters - `id` string, required ## Response `200` Activated earning rule - EarningRuleResponse — Earning rule as returned by the API. - `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` string, nullable — Earning item name. Nullable. - `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[], nullable — 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. - `period` EarningRuleEffectPointsExpirationRollingExpirationPeriod, required — Rolling expiration period. The maximum `value` depends on `unit`: `DAY` - 90, `MONTH` - 12, `YEAR` - 5. - … - `rounding` EarningRuleEffectPointsExpirationRollingExpirationRounding — Rounding of the rolling expiration date. `value` (the month number, 1-12) is required for `END_OF_PARTICULAR_MONTH` and must be null for all other rounding types. - … - `calendar_expiration` EarningRuleEffectPointsExpirationCalendarExpiration — Calendar expiration - points expire on fixed calendar dates (1 to 20 dates). - `expiration_dates` EarningRuleEffectPointsExpirationCalendarExpirationDate[], required — Fixed expiration dates (day + month). - … - `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). - `earning_activity` boolean — Whether earning activity resets the expiration window. - `spending_activity` boolean — Whether spending activity resets the expiration window. - `custom_activity` boolean — Whether the listed custom activity types reset the expiration window. - `custom_activity_types` string[], nullable — Custom activity type names. Required (1-10 unique items) when `custom_activity` is true. Nullable. - `period` EarningRuleEffectPointsExpirationSlidingExpirationPeriod, required — Sliding expiration inactivity period. The maximum `value` depends on `unit`: `DAY` - 90, `MONTH` - 12, `YEAR` - 1. - … - `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. - `period` EarningRuleEffectPointsExpirationRollingExpirationPeriod, required — Rolling expiration period. The maximum `value` depends on `unit`: `DAY` - 90, `MONTH` - 12, `YEAR` - 5. - … - `rounding` EarningRuleEffectPointsExpirationRollingExpirationRounding — Rounding of the rolling expiration date. `value` (the month number, 1-12) is required for `END_OF_PARTICULAR_MONTH` and must be null for all other rounding types. - … - `calendar_expiration` EarningRuleEffectPointsExpirationCalendarExpiration — Calendar expiration - points expire on fixed calendar dates (1 to 20 dates). - `expiration_dates` EarningRuleEffectPointsExpirationCalendarExpirationDate[], required — Fixed expiration dates (day + month). - … - `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). - `earning_activity` boolean — Whether earning activity resets the expiration window. - `spending_activity` boolean — Whether spending activity resets the expiration window. - `custom_activity` boolean — Whether the listed custom activity types reset the expiration window. - `custom_activity_types` string[], nullable — Custom activity type names. Required (1-10 unique items) when `custom_activity` is true. Nullable. - `period` EarningRuleEffectPointsExpirationSlidingExpirationPeriod, required — Sliding expiration inactivity period. The maximum `value` depends on `unit`: `DAY` - 90, `MONTH` - 12, `YEAR` - 1. - … - `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. - `every` integer, required — The divisor - every this amount (e.g. in cents) awards `value` points. - `value` number, required — Points awarded per `every` unit. - `total_amount` EarningRulePointsProportionalEvery — "Every X gives Y points" formula based on an amount. - `every` integer, required — The divisor - every this amount (e.g. in cents) awards `value` points. - `value` number, required — Points awarded per `every` unit. - `metadata` EarningRulePointsProportionalMetadata — "Every X gives Y points" formula based on a numeric metadata property. - `every` integer, required — The divisor - every this metadata value awards `value` points. - `value` number, required — Points awarded per `every` unit. - `property` string, required — Metadata property name holding the numeric value. - `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. - `every` integer, required — The divisor - every this metadata value awards `value` points. - `value` number, required — Points awarded per `every` unit. - `property` string, required — Metadata property name holding the numeric value. - `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. - `every` integer, required — The divisor - every this metadata value awards `value` points. - `value` number, required — Points awarded per `every` unit. - `property` string, required — Metadata property name holding the numeric value. - `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. - `every` integer, required — The divisor - every this amount/quantity awards `value` points. - `value` number, required — Points awarded per `every` unit. - `applicable_to` EarningRulePointsProportionalApplicableTo[], required — Product/SKU/collection criteria selecting matching order items. - … - `subtotal_amount` EarningRulePointsProportionalOrderItemsCalculation — Order items based calculation - "every X gives Y points" applied to items matching the `applicable_to` criteria. - `every` integer, required — The divisor - every this amount/quantity awards `value` points. - `value` number, required — Points awarded per `every` unit. - `applicable_to` EarningRulePointsProportionalApplicableTo[], required — Product/SKU/collection criteria selecting matching order items. - … - `quantity` EarningRulePointsProportionalOrderItemsCalculation — Order items based calculation - "every X gives Y points" applied to items matching the `applicable_to` criteria. - `every` integer, required — The divisor - every this amount/quantity awards `value` points. - `value` number, required — Points awarded per `every` unit. - `applicable_to` EarningRulePointsProportionalApplicableTo[], required — Product/SKU/collection criteria selecting matching order items. - … - `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[], nullable — 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, nullable — Date-time from which the rule is active. Nullable. - `end_date` string, date-time, nullable — 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[], nullable — 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. - `unit` 'DAY' | 'WEEK' | 'MONTH' | 'QUARTER' | 'YEAR', required — Calendar period unit. - `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, nullable — Last update timestamp (ISO 8601). Null when never updated. - `object` 'earning_rule' — Object type marker. Always `earning_rule`. ## 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/f6f2f3388362/schema)