--- title: "Examine earning rules" method: POST path: "/v2/loyalties/examine/earning-rules" tags: ["Examine"] --- # Examine earning rules `POST /v2/loyalties/examine/earning-rules` Estimates earning opportunities for a customer without triggering any actual earning for loyalty v2 earning rules. The `trigger` selects whether all trigger events or one specific event is examined. When a specific event is selected, exactly one matching context object is required: `customer_order_paid` for `customer.order.paid`, `customer_segment_entered` for `customer.segment.entered`, and `customer_custom_event` for `customer.custom_event`. The other context objects must not be present. This endpoint can examine earning rules for all loyalty programs the customer belongs to by using `customer_identification` with `customer_id` or `customer_source_id`. To examine earning rules only for one program, use `member_id` in `customer_identification`, as `member_id` is loyalty program-specific. ## Request body - ExamineEarningRulesRequest — Request body for examining earning rules. When `trigger.type` is `SPECIFIC`, the context object matching the specific event is required and the other context objects must not be present: `customer.order.paid` > `customer_order_paid`, `customer.segment.entered` > `customer_segment_entered`, `customer.custom_event` > `customer_custom_event`. - `trigger` ExamineEarningRulesTrigger, required — Which trigger events to examine. With `ALL`, all trigger events are examined and `specific` must be `null`/absent. With `SPECIFIC`, `specific` is required. - `type` 'ALL' | 'SPECIFIC', required — Trigger examination mode. - `specific` ExamineEarningRulesTriggerSpecific — Specific trigger event to examine. - `event` 'customer.order.paid' | 'customer.segment.entered' | 'customer.custom_event', required — Trigger event. - `customer_identification` ExamineCustomerIdentification, required — Identifies the customer to examine. Depending on `type`, requires one of `customer_id`, `customer_source_id`, or `member_id`. Non-selected identifiers may be omitted or set to `null`. - `type` 'customer_id' | 'customer_source_id' | 'member_id', required — Identification method. - `customer_id` string, nullable — Unique customer ID (`cust_...`). Required when `type` is `customer_id`. - `customer_source_id` union — Customer source ID, e.g. from an external system. May be provided as a string or a number. Required when `type` is `customer_source_id`. - string - number - `member_id` string, nullable — Loyalty member ID (`lmbr_...`). Required when `type` is `member_id`. - `customer_order_paid` ExamineEarningRulesCustomerOrderPaid — Context for examining `customer.order.paid` earning rules. - `customer` ExamineEarningRulesCustomer — Customer metadata overrides used during examination. - `metadata` Metadata — Arbitrary key-value metadata; any JSON object is accepted. - `member` ExamineEarningRulesMember — Member metadata overrides used during examination. Allowed only when `customer_identification.type` is `member_id`. - `metadata` Metadata — Arbitrary key-value metadata; any JSON object is accepted. - `order` ExamineEarningRulesOrder — A hypothetical order used for estimation. For earning rules that calculate points proportionally, pass the whole cart content, including `items`, `discount_amount`, etc. - `amount` union — Order amount after discounts - a non-negative integer. May be provided as a string or a number. Can be `null`. - string - number - `initial_amount` union — Order amount before discounts - a non-negative integer. May be provided as a string or a number. Can be `null`. - string - number - `discount_amount` union — Total discount amount - a non-negative integer. May be provided as a string or a number. Can be `null`. - string - number - `items` ExamineEarningRulesOrderItem[], nullable — Order line items (up to 500). Can be `null`. - `id` string, nullable — Order item ID assigned by Voucherify. Can be `null`. - `source_id` union — Order item source ID, e.g. from an external system. May be provided as a string or a number. Can be `null`. - string - number - `product_id` union — Product ID. May be provided as a string or a number. Can be `null`. - string - number - `sku_id` union — SKU ID. May be provided as a string or a number. Can be `null`. - string - number - `related_object` 'product' | 'sku', nullable — Whether the item refers to a product or a SKU. Can be `null`. - `amount` union — Item amount before discounts - a non-negative integer. May be provided as a string or a number. Can be `null`. - string - number - `discount_amount` union — Item discount amount - a non-negative integer. May be provided as a string or a number. Can be `null`. - string - number - `quantity` union — Item quantity - a positive integer. May be provided as a string or a number. Can be `null`. - string - number - `price` union — Item unit price - a non-negative integer. May be provided as a string or a number. Can be `null`. - string - number - `product` ExamineEarningRulesOrderItemProduct — Product details for an examined order item. - `id` union — Product ID. May be provided as a string or a number. Can be `null`. - string - number - `source_id` union — Product source ID. May be provided as a string or a number. Can be `null`. - string - number - `price` union — Product price - an integer amount. May be provided as a string or a number. Can be `null`. - string - number - `sku` ExamineEarningRulesOrderItemSku — SKU details for an examined order item. - `id` union — SKU ID. May be provided as a string or a number. Can be `null`. - string - number - `source_id` union — SKU source ID. May be provided as a string or a number. Can be `null`. - string - number - `price` union — SKU price - an integer amount. May be provided as a string or a number. Can be `null`. - string - number - `metadata` Metadata — Arbitrary key-value metadata; any JSON object is accepted. - `metadata` Metadata — Arbitrary key-value metadata; any JSON object is accepted. - `customer_segment_entered` ExamineEarningRulesCustomerSegmentEntered — Context for examining `customer.segment.entered` earning rules. Examine earning rule will work only for dynamic segments whose entry criteria are based on customer or member metadata, among other criteria. However, earning rules based on segments can be checked with the `ALL` scenario. - `customer` ExamineEarningRulesCustomer — Customer metadata overrides used during examination. - `metadata` Metadata — Arbitrary key-value metadata; any JSON object is accepted. - `member` ExamineEarningRulesMember — Member metadata overrides used during examination. Allowed only when `customer_identification.type` is `member_id`. - `metadata` Metadata — Arbitrary key-value metadata; any JSON object is accepted. - `customer_custom_event` ExamineEarningRulesCustomerCustomEvent — Context for examining `customer.custom_event` earning rules. With `type` = `ALL`, `all` is required and `specific` must be `null`/absent. With `SPECIFIC`, `specific` is required and `all` must be null/absent. - `type` 'ALL' | 'SPECIFIC', required — Whether to examine all custom events or one specific event. - `all` ExamineEarningRulesCustomerCustomEventAll — Context for examining all custom events. - `customer` ExamineEarningRulesCustomer — Customer metadata overrides used during examination. - `metadata` Metadata — Arbitrary key-value metadata; any JSON object is accepted. - `member` ExamineEarningRulesMember — Member metadata overrides used during examination. Allowed only when `customer_identification.type` is `member_id`. - `metadata` Metadata — Arbitrary key-value metadata; any JSON object is accepted. - `custom_event` ExamineEarningRulesCustomEventAll — Metadata applied when examining all custom events. - `metadata` Metadata — Arbitrary key-value metadata; any JSON object is accepted. - `specific` ExamineEarningRulesCustomerCustomEventSpecific — Context for examining a specific custom event. - `customer` ExamineEarningRulesCustomer — Customer metadata overrides used during examination. - `metadata` Metadata — Arbitrary key-value metadata; any JSON object is accepted. - `member` ExamineEarningRulesMember — Member metadata overrides used during examination. Allowed only when `customer_identification.type` is `member_id`. - `metadata` Metadata — Arbitrary key-value metadata; any JSON object is accepted. - `custom_event` ExamineEarningRulesCustomEventSpecific, required — A specific custom event to examine. - `schema_id` string, required — Custom event schema ID (`ms_...`). - `metadata` Metadata — Arbitrary key-value metadata; any JSON object is accepted. ## Response `200` Earning rules examination result - ExamineEarningRulesResponse - `event` string, nullable — Examined trigger event (e.g. `customer.order.paid`, `customer.segment.entered`, `customer.custom_event`). `null` when `trigger.type` is `ALL`. - `customer` ExamineCustomerReference — Customer reference in examine results. - `id` string, required — Unique customer ID (`cust_...`). - `source_id` string, nullable, required — Customer source ID. - `metadata` object, required — Customer metadata (empty object when unset). - `object` 'customer', required — Object type marker. Always `customer`. - `earning_rules` ExamineEarningRuleDetail[] — All earning rules that matched during examination (deduplicated). - `id` string — Earning rule ID (`lern_...`). - `name` string — Earning rule name. - `metadata` object — Earning rule metadata (empty object when unset). - `object` 'earning_rule' — Object type marker. Always `earning_rule`. - `memberships` ExamineEarningRulesMembership[] — Earning opportunities per program membership. - `member` ExamineMemberReference — Member reference in examine results. - `id` string, required — Unique member ID (`lmbr_...`). - `customer_id` string, required — Unique customer ID the member belongs to. - `program_id` string, required — Unique program ID the member belongs to. - `metadata` object, required — Member metadata (empty object when unset). - `object` 'member', required — Object type marker. Always `member`. - `program` ExamineProgramReference — Program reference in examine results. - `id` string, required — Unique program ID (`lprg_...`). - `name` string, required — Program name. - `metadata` object, required — Program metadata (empty object when unset). - `object` 'program', required — Object type marker. Always `program`. - `cards` ExamineEarningRulesCardEstimation[] — Point estimations per card. - `card` ExamineCardReference — Card reference in examine results. - `id` string, required — Unique card ID (`lcrd_...`). - `card_definition_id` string, required — Unique card definition ID (`lcdef_...`). - `card_type` 'INDIVIDUAL', required — Card type. Currently only `INDIVIDUAL` exists. - `code` string, nullable, required — Card code. May be `null` right after member creation because card codes are generated asynchronously. - `object` 'card', required — Object type marker. Always `card`. - `points_estimation` number — Total estimated points for the card across matching earning rules. - `earning_rules` ExamineEarningRulesCardEarningRuleEstimation[] — Per-earning-rule estimations contributing to the total. - `earning_rule` ExamineEarningRuleReference — Earning rule reference in examine results. - `id` string — Earning rule ID (`lern_...`). - `object` 'earning_rule' — Object type marker. Always `earning_rule`. - `points_estimation` number — Estimated points this earning rule would award to the card. - `object` 'earning_rule_estimation' — Object type marker. Always `earning_rule_estimation`. - `object` 'card_estimation' — Object type marker. Always `card_estimation`. - `benefits` ExamineEarningRulesBenefitEstimation[] — Benefit estimations. - `benefit` ExamineBenefitReference — Benefit reference in examine results. - `id` string — Benefit ID (`lben_...`). - `name` string — Benefit name. - `type` 'POINTS' | 'POINTS_PROPORTIONAL' | 'MATERIAL' | 'DIGITAL' — Benefit type. - `object` 'benefit' — Object type marker. Always `benefit`. - `earning_rules` ExamineEarningRulesBenefitEarningRuleEstimation[] — Earning rules that would grant this benefit. - `earning_rule` ExamineEarningRuleReference — Earning rule reference in examine results. - `id` string — Earning rule ID (`lern_...`). - `object` 'earning_rule' — Object type marker. Always `earning_rule`. - `object` 'earning_rule_estimation' — Object type marker. Always `earning_rule_estimation`. - `object` 'benefit_estimation' — Object type marker. Always `benefit_estimation`. - `object` 'member_earnings_opportunity' — Object type marker. Always `member_earnings_opportunity`. - `object` 'earnings_examine_result' — Object type marker. Always `earnings_examine_result`. ## Other responses - `400` — Validation error - request body failed validation. - `404` — Resource not found. - `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)