--- title: "Examine earning rules" method: POST path: "/v2/loyalties/examine/earning-rules" tags: ["Examine"] --- # Examine earning rules `POST /v2/loyalties/examine/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. Estimates earning opportunities for a customer without triggering any actual earning. 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). ## 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 — How the examined customer is identified. Depending on `type`, exactly one of `customer_id`, `customer_source_id` or `member_id` is required; the other two must not be present. - `type` 'customer_id' | 'customer_source_id' | 'member_id', required — Identification method. - `customer_id` unknown - `customer_source_id` unknown - `member_id` unknown - `customer_order_paid` ExamineEarningRulesCustomerOrderPaid — Context for examining `customer.order.paid` earning rules. - `customer` ExamineEarningRulesCustomer — Customer metadata overrides used during examination. - `metadata` EarningRuleMetadata — Arbitrary key-value metadata; any JSON object is accepted. - `member` ExamineEarningRulesMember — Member metadata overrides used during examination. - `metadata` EarningRuleMetadata — Arbitrary key-value metadata; any JSON object is accepted. - `order` ExamineEarningRulesOrder — A hypothetical order used for estimation. - `amount` unknown - `initial_amount` unknown - `discount_amount` unknown - `items` ExamineEarningRulesOrderItem[] — Order line items (up to 500). Nullable. - `id` unknown - `source_id` unknown - `product_id` unknown - `sku_id` unknown - `related_object` 'product' | 'sku' — Whether the item refers to a product or a SKU. Nullable. - `amount` unknown - `discount_amount` unknown - `quantity` unknown - `price` unknown - `product` ExamineEarningRulesOrderItemProduct — Product details for an examined order item. - `id` unknown - `source_id` unknown - `price` unknown - `sku` ExamineEarningRulesOrderItemSku — SKU details for an examined order item. - `id` unknown - `source_id` unknown - `price` unknown - `metadata` EarningRuleMetadata — Arbitrary key-value metadata; any JSON object is accepted. - `metadata` EarningRuleMetadata — Arbitrary key-value metadata; any JSON object is accepted. - `customer_segment_entered` ExamineEarningRulesCustomerSegmentEntered — Context for examining `customer.segment.entered` earning rules. - `customer` ExamineEarningRulesCustomer — Customer metadata overrides used during examination. - `metadata` EarningRuleMetadata — Arbitrary key-value metadata; any JSON object is accepted. - `member` ExamineEarningRulesMember — Member metadata overrides used during examination. - `metadata` EarningRuleMetadata — 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` EarningRuleMetadata — Arbitrary key-value metadata; any JSON object is accepted. - `member` ExamineEarningRulesMember — Member metadata overrides used during examination. - `metadata` EarningRuleMetadata — Arbitrary key-value metadata; any JSON object is accepted. - `custom_event` ExamineEarningRulesCustomEventAll — Metadata applied when examining all custom events. - `metadata` EarningRuleMetadata — 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` EarningRuleMetadata — Arbitrary key-value metadata; any JSON object is accepted. - `member` ExamineEarningRulesMember — Member metadata overrides used during examination. - `metadata` EarningRuleMetadata — 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` EarningRuleMetadata — Arbitrary key-value metadata; any JSON object is accepted. ## Response `200` Earning rules examination result - ExamineEarningRulesResponse — Earning rules examination result. - `event` string — Examined trigger event (e.g. `customer.order.paid`, `customer.segment.entered`, `customer.custom_event`). - `customer` ExamineCustomerReference — Customer reference in examine results. - `id` string — Customer ID (`cust_...`). - `source_id` string — Customer source ID. - `metadata` object — Customer metadata (empty object when unset). - `object` string — 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` string — Object type marker. Always `earning_rule`. - `memberships` ExamineEarningRulesMembership[] — Earning opportunities per program membership. - `member` ExamineMemberReference — Member reference in examine results. - `id` string — Member ID (`lmbr_...`). - `customer_id` string — Customer ID the member belongs to. - `program_id` string — Program ID the member belongs to. - `metadata` object — Member metadata (empty object when unset). - `object` string — Object type marker. Always `member`. - `program` ExamineProgramReference — Program reference in examine results. - `id` string — Program ID (`lprg_...`). - `name` string — Program name. - `metadata` object — Program metadata (empty object when unset). - `object` string — Object type marker. Always `program`. - `cards` ExamineEarningRulesCardEstimation[] — Points estimations per card. - `card` ExamineCardReference — Card reference in examine results. - `id` string — Card ID (`lcrd_...`). - `card_definition_id` string — Card definition ID (`lcdef_...`). - `card_type` 'INDIVIDUAL' — Card type. Currently only `INDIVIDUAL` exists. - `code` unknown - `object` string — 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` string — Object type marker. Always `earning_rule`. - `points_estimation` number — Estimated points this earning rule would award to the card. - `object` string — Object type marker. Always `earning_rule_estimation`. - `object` string — 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` string — 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` string — Object type marker. Always `earning_rule`. - `object` string — Object type marker. Always `earning_rule_estimation`. - `object` string — Object type marker. Always `benefit_estimation`. - `object` string — Object type marker. Always `member_earnings_opportunity`. - `object` string — Object type marker. Always `earnings_examine_result`. ## 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/revisions/4982266e0494/schema)