> ## Documentation Index
> Fetch the complete documentation index at: https://voucherify-rc-lv2-guides.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 be 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).
## OpenAPI
````yaml /openapi/loyalties-v2.json post /v2/loyalties/examine/earning-rules
openapi: 3.1.0
info:
title: Voucherify Loyalty v2 API
version: 2.0.0
description: >-
Complete OpenAPI specification for the Voucherify Loyalty v2 API.
All endpoints require the LOYALTY_V2 feature flag.
Combined from per-domain specs: programs.yaml, members.yaml,
program-operations.yaml, card-definitions.yaml, earning-rules.yaml,
tier-structures.yaml, benefits.yaml, rewards.yaml, examine.yaml
servers:
- url: '{protocol}://{host}'
variables:
protocol:
default: https
enum:
- https
- http
host:
default: api.voucherify.io
security:
- X-App-Id: []
X-App-Token: []
- bearerAuth: []
tags:
- name: Programs
description: >-
Loyalty program CRUD, lifecycle management, program-scoped resource
assignments (card definitions, earning rules, rewards, tier structures),
member management (create, list, get, activate, deactivate, delete),
membership retrieval (member + program + cards with tier progress, by
customer ID, customer source ID, or member ID), card operations (points
adjustment, pending points, expiring points, transactions), reward
purchases, and activity history.
- name: Card Definitions
description: >-
CRUD operations, lifecycle management, and activity history for card
definitions. Card definitions describe the configuration for loyalty
cards, including code generation, points expiration, earning/spending
limits, pending points, refunds, and balance settings.
- name: Earning Rules
description: >-
Manage earning rules that define how customers earn points or receive
incentives based on triggers (events, segments, custom events). Includes
CRUD, lifecycle, and activity history.
- name: Tier Structures
description: >-
CRUD operations, lifecycle management, and activity history for tier
structures. Includes nested tier definitions (create, list, update,
delete) within tier structures. Tier structures define the tiering model
for loyalty programs — how members qualify for and move between tiers.
- name: Benefits
description: >-
Manage benefit definitions (fixed points, proportional points, material,
digital). Includes CRUD, lifecycle transitions, and activity history.
- name: Rewards
description: >-
CRUD, lifecycle operations, and activity history for reward definitions.
Rewards can be material (product/SKU) or digital (discount coupons, gift
vouchers).
- name: Examine
description: >-
Evaluation endpoints that estimate earning opportunities and reward
availability for a customer across their loyalty program memberships,
without side effects.
paths:
/v2/loyalties/examine/earning-rules:
post:
tags:
- Examine
summary: Examine earning rules
description: >-
BETA endpoint
This is a work-in-progress documentation of a BETA endpoint. The
parameters, fields, request and response bodies, and other data may be
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).
operationId: examineEarningRules
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExamineEarningRulesRequest'
responses:
'200':
description: Earning rules examination result
content:
application/json:
schema:
$ref: '#/components/schemas/ExamineEarningRulesResponse'
'400':
description: >-
Validation error - request body or query parameters failed
validation, or the operation is not allowed in the current resource
state.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Conflict - e.g. duplicate resource or invalid state transition.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
ExamineEarningRulesRequest:
type: object
description: >-
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`.
properties:
trigger:
$ref: '#/components/schemas/ExamineEarningRulesTrigger'
customer_identification:
$ref: '#/components/schemas/ExamineCustomerIdentification'
customer_order_paid:
$ref: '#/components/schemas/ExamineEarningRulesCustomerOrderPaid'
customer_segment_entered:
$ref: '#/components/schemas/ExamineEarningRulesCustomerSegmentEntered'
customer_custom_event:
$ref: '#/components/schemas/ExamineEarningRulesCustomerCustomEvent'
required:
- trigger
- customer_identification
additionalProperties: false
allOf:
- if:
required:
- trigger
properties:
trigger:
properties:
type:
const: SPECIFIC
specific:
properties:
event:
const: customer.order.paid
then:
required:
- customer_order_paid
not:
anyOf:
- required:
- customer_segment_entered
- required:
- customer_custom_event
- if:
required:
- trigger
properties:
trigger:
properties:
type:
const: SPECIFIC
specific:
properties:
event:
const: customer.segment.entered
then:
required:
- customer_segment_entered
not:
anyOf:
- required:
- customer_order_paid
- required:
- customer_custom_event
- if:
required:
- trigger
properties:
trigger:
properties:
type:
const: SPECIFIC
specific:
properties:
event:
const: customer.custom_event
then:
required:
- customer_custom_event
not:
anyOf:
- required:
- customer_order_paid
- required:
- customer_segment_entered
ExamineEarningRulesResponse:
type: object
description: Earning rules examination result.
properties:
event:
type: string
description: >-
Examined trigger event (e.g. `customer.order.paid`,
`customer.segment.entered`, `customer.custom_event`).
customer:
$ref: '#/components/schemas/ExamineCustomerReference'
earning_rules:
type: array
description: All earning rules that matched during examination (deduplicated).
items:
$ref: '#/components/schemas/ExamineEarningRuleDetail'
memberships:
type: array
description: Earning opportunities per program membership.
items:
$ref: '#/components/schemas/ExamineEarningRulesMembership'
object:
type: string
const: earnings_examine_result
description: Object type marker. Always `earnings_examine_result`.
ErrorResponse:
type: object
description: Standard error response returned by all Loyalty v2 endpoints.
properties:
code:
type: integer
description: HTTP status code of the error.
key:
type: string
description: Machine-readable error key.
message:
type: string
description: Human-readable error message.
details:
type: string
description: Additional details about the error.
request_id:
type: string
description: Unique identifier of the request that produced the error.
resource_id:
type: string
description: Unique identifier of the resource that produced the error.
resource_type:
type: string
description: Type of the resource that produced the error.
ExamineEarningRulesTrigger:
type: object
description: >-
Which trigger events to examine. With `ALL`, all trigger events are
examined and `specific` must be null/absent. With `SPECIFIC`, `specific`
is required.
properties:
type:
type: string
enum:
- ALL
- SPECIFIC
description: Trigger examination mode.
specific:
description: Specific event selection. Nullable.
oneOf:
- $ref: '#/components/schemas/ExamineEarningRulesTriggerSpecific'
- type: 'null'
additionalProperties: false
allOf:
- required:
- type
- if:
properties:
type:
const: ALL
then:
properties:
specific:
type: 'null'
- if:
properties:
type:
const: SPECIFIC
then:
required:
- specific
properties:
specific:
$ref: '#/components/schemas/ExamineEarningRulesTriggerSpecific'
ExamineCustomerIdentification:
type: object
description: >-
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`.
properties:
type:
type: string
enum:
- customer_id
- customer_source_id
- member_id
description: Identification method.
customer_id:
type:
- string
- 'null'
pattern: ^cust_[a-zA-Z0-9]+
description: >-
Unique customer ID (`cust_...`). Required when `type` is
`customer_id`.
customer_source_id:
type:
- string
- number
- 'null'
description: >-
Customer source ID. May be provided as a string or a number.
Required when `type` is `customer_source_id`.
member_id:
type:
- string
- 'null'
pattern: ^lmbr_[a-f0-9]+$
description: Loyalty member ID (`lmbr_...`). Required when `type` is `member_id`.
required:
- type
additionalProperties: false
allOf:
- if:
required:
- type
properties:
type:
const: customer_id
then:
required:
- customer_id
properties:
customer_source_id:
type: 'null'
member_id:
type: 'null'
- if:
required:
- type
properties:
type:
const: customer_source_id
then:
required:
- customer_source_id
properties:
customer_id:
type: 'null'
member_id:
type: 'null'
- if:
required:
- type
properties:
type:
const: member_id
then:
required:
- member_id
properties:
customer_id:
type: 'null'
customer_source_id:
type: 'null'
ExamineEarningRulesCustomerOrderPaid:
type: object
description: Context for examining `customer.order.paid` earning rules.
properties:
customer:
$ref: '#/components/schemas/ExamineEarningRulesCustomer'
member:
$ref: '#/components/schemas/ExamineEarningRulesMember'
order:
$ref: '#/components/schemas/ExamineEarningRulesOrder'
additionalProperties: false
ExamineEarningRulesCustomerSegmentEntered:
type: object
description: Context for examining `customer.segment.entered` earning rules.
properties:
customer:
$ref: '#/components/schemas/ExamineEarningRulesCustomer'
member:
$ref: '#/components/schemas/ExamineEarningRulesMember'
additionalProperties: false
ExamineEarningRulesCustomerCustomEvent:
type: object
description: >-
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.
properties:
type:
type: string
enum:
- ALL
- SPECIFIC
description: Whether to examine all custom events or one specific event.
all:
description: Context for all custom events. Nullable.
oneOf:
- $ref: '#/components/schemas/ExamineEarningRulesCustomerCustomEventAll'
- type: 'null'
specific:
description: Context for a specific custom event. Nullable.
oneOf:
- $ref: >-
#/components/schemas/ExamineEarningRulesCustomerCustomEventSpecific
- type: 'null'
additionalProperties: false
allOf:
- required:
- type
- if:
properties:
type:
const: ALL
then:
required:
- all
properties:
specific:
type: 'null'
- if:
properties:
type:
const: SPECIFIC
then:
required:
- specific
properties:
all:
type: 'null'
specific:
$ref: >-
#/components/schemas/ExamineEarningRulesCustomerCustomEventSpecific
ExamineCustomerReference:
type: object
description: Customer reference in examine results.
properties:
id:
type: string
description: Unique customer ID (`cust_...`).
source_id:
type: string
description: Customer source ID.
metadata:
type: object
description: Customer metadata (empty object when unset).
additionalProperties: true
object:
type: string
const: customer
description: Object type marker. Always `customer`.
required:
- id
- source_id
- metadata
- object
ExamineEarningRuleDetail:
type: object
description: Earning rule detail in examine results.
properties:
id:
type: string
description: Earning rule ID (`lern_...`).
name:
type: string
description: Earning rule name.
metadata:
type: object
description: Earning rule metadata (empty object when unset).
additionalProperties: true
object:
type: string
const: earning_rule
description: Object type marker. Always `earning_rule`.
ExamineEarningRulesMembership:
type: object
description: Earning opportunities for one program membership.
properties:
member:
$ref: '#/components/schemas/ExamineMemberReference'
program:
$ref: '#/components/schemas/ExamineProgramReference'
cards:
type: array
description: Point estimations per card.
items:
$ref: '#/components/schemas/ExamineEarningRulesCardEstimation'
benefits:
type: array
description: Benefit estimations.
items:
$ref: '#/components/schemas/ExamineEarningRulesBenefitEstimation'
object:
type: string
const: member_earnings_opportunity
description: Object type marker. Always `member_earnings_opportunity`.
ExamineEarningRulesTriggerSpecific:
type: object
description: Specific trigger event to examine.
properties:
event:
type: string
enum:
- customer.order.paid
- customer.segment.entered
- customer.custom_event
description: Trigger event.
required:
- event
additionalProperties: false
ExamineEarningRulesCustomer:
type: object
description: Customer metadata overrides used during examination.
properties:
metadata:
description: Customer metadata overrides. Nullable.
oneOf:
- $ref: '#/components/schemas/Metadata'
- type: 'null'
additionalProperties: false
ExamineEarningRulesMember:
type: object
description: Member metadata overrides used during examination.
properties:
metadata:
description: Member metadata overrides. Nullable.
oneOf:
- $ref: '#/components/schemas/Metadata'
- type: 'null'
additionalProperties: false
ExamineEarningRulesOrder:
type: object
description: A hypothetical order used for estimation.
properties:
amount:
type:
- string
- number
- 'null'
description: >-
Order amount after discounts - a non-negative integer. May be
provided as a string or a number. Nullable.
initial_amount:
type:
- string
- number
- 'null'
description: >-
Order amount before discounts - a non-negative integer. May be
provided as a string or a number. Nullable.
discount_amount:
type:
- string
- number
- 'null'
description: >-
Total discount amount - a non-negative integer. May be provided as a
string or a number. Nullable.
items:
type:
- array
- 'null'
maxItems: 500
description: Order line items (up to 500). Nullable.
items:
$ref: '#/components/schemas/ExamineEarningRulesOrderItem'
metadata:
description: Order metadata. Nullable.
oneOf:
- $ref: '#/components/schemas/Metadata'
- type: 'null'
additionalProperties: false
ExamineEarningRulesCustomerCustomEventAll:
type: object
description: Context for examining all custom events.
properties:
customer:
$ref: '#/components/schemas/ExamineEarningRulesCustomer'
member:
$ref: '#/components/schemas/ExamineEarningRulesMember'
custom_event:
$ref: '#/components/schemas/ExamineEarningRulesCustomEventAll'
additionalProperties: false
ExamineEarningRulesCustomerCustomEventSpecific:
type: object
description: Context for examining a specific custom event.
properties:
customer:
$ref: '#/components/schemas/ExamineEarningRulesCustomer'
member:
$ref: '#/components/schemas/ExamineEarningRulesMember'
custom_event:
$ref: '#/components/schemas/ExamineEarningRulesCustomEventSpecific'
required:
- custom_event
additionalProperties: false
ExamineMemberReference:
type: object
description: Member reference in examine results.
properties:
id:
type: string
description: Unique member ID (`lmbr_...`).
customer_id:
type: string
description: Unique customer ID the member belongs to.
program_id:
type: string
description: Unique program ID the member belongs to.
metadata:
type: object
description: Member metadata (empty object when unset).
additionalProperties: true
object:
type: string
const: member
description: Object type marker. Always `member`.
required:
- id
- customer_id
- program_id
- metadata
- object
ExamineProgramReference:
type: object
description: Program reference in examine results.
properties:
id:
type: string
description: Unique program ID (`lprg_...`).
name:
type: string
description: Program name.
metadata:
type: object
description: Program metadata (empty object when unset).
additionalProperties: true
object:
type: string
description: Object type marker. Always `program`.
const: program
required:
- id
- name
- metadata
- object
ExamineEarningRulesCardEstimation:
type: object
description: Point estimation for a single card.
properties:
card:
$ref: '#/components/schemas/ExamineCardReference'
points_estimation:
type: number
description: Total estimated points for the card across matching earning rules.
earning_rules:
type: array
description: Per-earning-rule estimations contributing to the total.
items:
$ref: '#/components/schemas/ExamineEarningRulesCardEarningRuleEstimation'
object:
type: string
const: card_estimation
description: Object type marker. Always `card_estimation`.
ExamineEarningRulesBenefitEstimation:
type: object
description: Benefit estimation.
properties:
benefit:
$ref: '#/components/schemas/ExamineBenefitReference'
earning_rules:
type: array
description: Earning rules that would grant this benefit.
items:
$ref: >-
#/components/schemas/ExamineEarningRulesBenefitEarningRuleEstimation
object:
type: string
const: benefit_estimation
description: Object type marker. Always `benefit_estimation`.
Metadata:
type: object
description: Arbitrary key-value metadata; any JSON object is accepted.
additionalProperties: true
ExamineEarningRulesOrderItem:
type: object
description: A hypothetical order line item used for estimation.
properties:
id:
type:
- string
- 'null'
description: Order item ID. Nullable.
source_id:
type:
- string
- number
- 'null'
description: >-
Order item source ID. May be provided as a string or a number.
Nullable.
product_id:
type:
- string
- number
- 'null'
description: Product ID. May be provided as a string or a number. Nullable.
sku_id:
type:
- string
- number
- 'null'
description: SKU ID. May be provided as a string or a number. Nullable.
related_object:
description: Whether the item refers to a product or a SKU. Nullable.
oneOf:
- type: string
enum:
- product
- sku
- type: 'null'
amount:
type:
- string
- number
- 'null'
description: >-
Item amount before discounts - a non-negative integer. May be
provided as a string or a number. Nullable.
discount_amount:
type:
- string
- number
- 'null'
description: >-
Item discount amount - a non-negative integer. May be provided as a
string or a number. Nullable.
quantity:
type:
- string
- number
- 'null'
description: >-
Item quantity - a positive integer. May be provided as a string or a
number. Nullable.
price:
type:
- string
- number
- 'null'
description: >-
Item unit price - a non-negative integer. May be provided as a
string or a number. Nullable.
product:
description: Product details. Nullable.
oneOf:
- $ref: '#/components/schemas/ExamineEarningRulesOrderItemProduct'
- type: 'null'
sku:
description: SKU details. Nullable.
oneOf:
- $ref: '#/components/schemas/ExamineEarningRulesOrderItemSku'
- type: 'null'
metadata:
description: Order item metadata. Nullable.
oneOf:
- $ref: '#/components/schemas/Metadata'
- type: 'null'
additionalProperties: false
ExamineEarningRulesCustomEventAll:
type: object
description: Metadata applied when examining all custom events.
properties:
metadata:
description: Custom event metadata. Nullable.
oneOf:
- $ref: '#/components/schemas/Metadata'
- type: 'null'
additionalProperties: false
ExamineEarningRulesCustomEventSpecific:
type: object
description: A specific custom event to examine.
properties:
schema_id:
type: string
pattern: ^ms_[a-zA-Z0-9]+
description: Custom event schema ID (`ms_...`).
metadata:
description: Custom event metadata. Nullable.
oneOf:
- $ref: '#/components/schemas/Metadata'
- type: 'null'
required:
- schema_id
additionalProperties: false
ExamineCardReference:
type: object
description: Card reference in examine results.
properties:
id:
type: string
description: Unique card ID (`lcrd_...`).
card_definition_id:
type: string
description: Unique card definition ID (`lcdef_...`).
card_type:
type: string
enum:
- INDIVIDUAL
description: Card type. Currently only `INDIVIDUAL` exists.
code:
type:
- string
- 'null'
description: >-
Card code. May be `null` right after member creation because card
codes are generated asynchronously.
object:
type: string
const: card
description: Object type marker. Always `card`.
required:
- id
- card_definition_id
- card_type
- code
- object
ExamineEarningRulesCardEarningRuleEstimation:
type: object
description: Point estimation from a single earning rule for a card.
properties:
earning_rule:
$ref: '#/components/schemas/ExamineEarningRuleReference'
points_estimation:
type: number
description: Estimated points this earning rule would award to the card.
object:
type: string
const: earning_rule_estimation
description: Object type marker. Always `earning_rule_estimation`.
ExamineBenefitReference:
type: object
description: Benefit reference in examine results.
properties:
id:
type: string
description: Benefit ID (`lben_...`).
name:
type: string
description: Benefit name.
type:
type: string
enum:
- POINTS
- POINTS_PROPORTIONAL
- MATERIAL
- DIGITAL
description: Benefit type.
object:
type: string
const: benefit
description: Object type marker. Always `benefit`.
ExamineEarningRulesBenefitEarningRuleEstimation:
type: object
description: Earning rule granting a benefit.
properties:
earning_rule:
$ref: '#/components/schemas/ExamineEarningRuleReference'
object:
type: string
const: earning_rule_estimation
description: Object type marker. Always `earning_rule_estimation`.
ExamineEarningRulesOrderItemProduct:
type: object
description: Product details for an examined order item.
properties:
id:
type:
- string
- number
- 'null'
description: Product ID. May be provided as a string or a number. Nullable.
source_id:
type:
- string
- number
- 'null'
description: >-
Product source ID. May be provided as a string or a number.
Nullable.
price:
type:
- string
- number
- 'null'
description: >-
Product price - an integer amount of at most 9007199254740991. May
be provided as a string or a number. Nullable.
additionalProperties: false
ExamineEarningRulesOrderItemSku:
type: object
description: SKU details for an examined order item.
properties:
id:
type:
- string
- number
- 'null'
description: SKU ID. May be provided as a string or a number. Nullable.
source_id:
type:
- string
- number
- 'null'
description: SKU source ID. May be provided as a string or a number. Nullable.
price:
type:
- string
- number
- 'null'
description: >-
SKU price - an integer amount of at most 9007199254740991. May be
provided as a string or a number. Nullable.
additionalProperties: false
ExamineEarningRuleReference:
type: object
description: Earning rule reference in examine results.
properties:
id:
type: string
description: Earning rule ID (`lern_...`).
object:
type: string
const: earning_rule
description: Object type marker. Always `earning_rule`.
securitySchemes:
X-App-Id:
type: apiKey
name: X-App-Id
in: header
X-App-Token:
type: apiKey
name: X-App-Token
in: header
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````