--- title: "Examine earning rules" method: POST path: "/v2/loyalties/examine/earning-rules" tags: ["Examine"] --- # Examine earning rules `POST /v2/loyalties/examine/earning-rules` ## Request - Base URL: `https://api.voucherify.io` - URL: `https://api.voucherify.io/v2/loyalties/examine/earning-rules` - Auth: one of: - API key in header `X-App-Id` and API key in header `X-App-Token` - HTTP bearer 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. A customer who exists but has no active membership returns `200` with an empty `memberships` array. ## Request body - LoyaltiesExamineEarningRulesExamineRequestBody: Request body schema for **POST** `/v2/loyalties/examine/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` LoyaltiesExamineEarningRulesExamineRequestBodyTrigger, 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` LoyaltiesExamineEarningRulesExamineRequestBodyTriggerSpecific: 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` LoyaltiesExamineEarningRulesExamineRequestBodyCustomerOrderPaid: Context for examining `customer.order.paid` earning rules. - `customer` LoyaltiesExamineEarningRulesExamineRequestBodyCustomer: Customer metadata overrides used during examination. - `metadata` LoyaltyV2ActivityMetadata: Arbitrary key-value metadata; any JSON object is accepted. - `member` LoyaltiesExamineEarningRulesExamineRequestBodyMember: Member metadata overrides used during examination. Allowed only when `customer_identification.type` is `member_id`. - `metadata` LoyaltyV2ActivityMetadata: Arbitrary key-value metadata; any JSON object is accepted. - `order` LoyaltiesExamineEarningRulesExamineRequestBodyOrder: 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` LoyaltiesExamineEarningRulesExamineRequestBodyOrderItem[], 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` LoyaltiesExamineEarningRulesExamineRequestBodyOrderItemProduct: 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` LoyaltiesExamineEarningRulesExamineRequestBodyOrderItemSku: 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` LoyaltyV2ActivityMetadata: Arbitrary key-value metadata; any JSON object is accepted. - `metadata` LoyaltyV2ActivityMetadata: Arbitrary key-value metadata; any JSON object is accepted. - `customer_segment_entered` LoyaltiesExamineEarningRulesExamineRequestBodyCustomerSegmentEntered - `customer` LoyaltiesExamineEarningRulesExamineRequestBodyCustomer: Customer metadata overrides used during examination. - `metadata` LoyaltyV2ActivityMetadata: Arbitrary key-value metadata; any JSON object is accepted. - `member` LoyaltiesExamineEarningRulesExamineRequestBodyMember: Member metadata overrides used during examination. Allowed only when `customer_identification.type` is `member_id`. - `metadata` LoyaltyV2ActivityMetadata: Arbitrary key-value metadata; any JSON object is accepted. - `customer_custom_event` LoyaltiesExamineEarningRulesExamineRequestBodyCustomerCustomEvent: 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` LoyaltiesExamineEarningRulesExamineRequestBodyCustomerCustomEventAll: Context for examining all custom events. - `customer` LoyaltiesExamineEarningRulesExamineRequestBodyCustomer: Customer metadata overrides used during examination. - `metadata` LoyaltyV2ActivityMetadata: Arbitrary key-value metadata; any JSON object is accepted. - `member` LoyaltiesExamineEarningRulesExamineRequestBodyMember: Member metadata overrides used during examination. Allowed only when `customer_identification.type` is `member_id`. - `metadata` LoyaltyV2ActivityMetadata: Arbitrary key-value metadata; any JSON object is accepted. - `custom_event` LoyaltiesExamineEarningRulesExamineRequestBodyCustomEventAll: Metadata applied when examining all custom events. - `metadata` LoyaltyV2ActivityMetadata: Arbitrary key-value metadata; any JSON object is accepted. - `specific` LoyaltiesExamineEarningRulesExamineRequestBodyCustomerCustomEventSpecific: Context for examining a specific custom event. - `customer` LoyaltiesExamineEarningRulesExamineRequestBodyCustomer: Customer metadata overrides used during examination. - `metadata` LoyaltyV2ActivityMetadata: Arbitrary key-value metadata; any JSON object is accepted. - `member` LoyaltiesExamineEarningRulesExamineRequestBodyMember: Member metadata overrides used during examination. Allowed only when `customer_identification.type` is `member_id`. - `metadata` LoyaltyV2ActivityMetadata: Arbitrary key-value metadata; any JSON object is accepted. - `custom_event` LoyaltiesExamineEarningRulesExamineRequestBodyCustomEventSpecific, required: A specific custom event to examine. - `schema_id` string, required: Custom event schema ID (`ms_...`). - `metadata` LoyaltyV2ActivityMetadata: Arbitrary key-value metadata; any JSON object is accepted. ## Response `200` Earning rules examination result. An empty `memberships` array means no active membership has earning rules for the examined trigger. - LoyaltiesExamineEarningRulesExamineResponseBody: Response body schema for **POST** `/v2/loyalties/examine/earning-rules`. - `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` LoyaltiesExamineEarningRulesExamineResponseBodyEarningRuleDetail[]: Lists earning rules that produced a points or benefit estimation, deduplicated across memberships. - `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` LoyaltiesExamineEarningRulesExamineResponseBodyMembership[]: Lists one entry for each active membership whose program has earning rules for the examined trigger. Includes a card only when its estimated points are greater than 0, and a benefit only when an earning rule can grant it. Both arrays can be empty. - `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` LoyaltiesExamineEarningRulesExamineResponseBodyCardEstimation[]: 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` LoyaltiesExamineEarningRulesExamineResponseBodyCardEarningRuleEstimation[]: Per-earning-rule estimations contributing to the total. - `earning_rule` LoyaltiesExamineEarningRulesExamineResponseBodyEarningRuleReference: 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`. - `points_estimation` number: Estimated points this earning rule would award to the card. - `object` 'card_estimation': Object type marker. Always `card_estimation`. - `benefits` LoyaltiesExamineEarningRulesExamineResponseBodyBenefitEstimation[]: Benefit estimations. - `benefit` LoyaltiesExamineEarningRulesExamineResponseBodyBenefitReference: 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` LoyaltiesExamineEarningRulesExamineResponseBodyBenefitEarningRuleEstimation[]: Earning rules that would grant this benefit. - `earning_rule` LoyaltiesExamineEarningRulesExamineResponseBodyEarningRuleReference: 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. Temporary customer, member, or order metadata that does not match its metadata schema returns key `metadata_validation_failed` and message `Metadata validation failed`. - `404`: The `member_id` does not exist, or the `customer_id` or `customer_source_id` does not exist. An unknown `member_id` is checked first and returns `resource_type` `member` with details `Cannot find member with id {memberId}`. An unknown customer returns `resource_type` `customer` with details `Cannot find customer with id {id}`, where `{id}` is the `customer_id` or `customer_source_id` you sent. When a member exists but its customer record does not, that same customer error uses the `member_id` as `{id}`. - `500`: Internal server error. ## Changes - **2026-10-14** (v2) `d29b33490051`: 12 breaking, 19 warning, 2 info - added `#/components/schemas/ExamineCustomerContextBase` to the `customer_segment_entered` request property `allOf` list - added `#/components/schemas/ExamineCustomerContextBase, subschema #2` to the `customer_custom_event/all/oneOf[subschema #1: Loyalties Examine Earning Rules Examine Request Body Customer Custom Event All]/` request property `allOf` list - added `#/components/schemas/ExamineCustomerContextBase, subschema #2` to the `customer_custom_event/allOf[subschema #3]/then/specific` request property `allOf` list - added `#/components/schemas/ExamineCustomerContextBase, subschema #2` to the `customer_custom_event/specific/oneOf[subschema #1: Loyalties Examine Earning Rules Examine Request Body Customer Custom Event Specific]/` request property `allOf` list - …29 more - …earlier changes not shown [Operation history](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/changes/v2/loyalties/examine/earning-rules/post.md) --- [API](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api.md) - [All operations](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/revisions/e0d9f2d2532f?raw)