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. A customer who exists but has no active membership returns 200 with an empty memberships array.

POST /v2/loyalties/examine/earning-rules

cURL

All triggers

curl --request POST \
  --url https://{cluster}.voucherify.io/v2/loyalties/examine/earning-rules \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "trigger": {
    "type": "ALL"
  },
  "customer_identification": {
    "type": "member_id",
    "member_id": "lmbr_128f962dbc8c4ba5dc"
  },
  "customer_order_paid": {
    "customer": {
      "metadata": {
        "tier": "gold"
      }
    },
    "member": {
      "metadata": {
        "channel": "mobile"
      }
    },
    "order": {
      "amount": 10000,
      "metadata": {
        "source": "pos"
      }
    }
  },
  "customer_segment_entered": {
    "customer": {
      "metadata": {
        "is_premium": "true",
        "loyalty_score": 10
      }
    }
  },
  "customer_custom_event": {
    "type": "ALL",
    "all": {
      "customer": {
        "metadata": {
          "plan": "pro"
        }
      },
      "custom_event": {
        "metadata": {
          "source": "mobile",
          "score": 40
        }
      }
    }
  }
}
'

200

All triggers without additional data

{
  "event": null,
  "customer": {
    "id": "cust_6onRrs4kCnvSVrTs5YtDPFBG",
    "source_id": "lx-rdmptr",
    "metadata": {
      "VIP": true
    },
    "object": "customer"
  },
  "earning_rules": [
    {
      "id": "lern_128f577bd4d47c8e12",
      "name": "EnterVipSegment",
      "metadata": {},
      "object": "earning_rule"
    },
    {
      "id": "lern_128f5822398c4bf78f",
      "name": "AutumnPaid",
      "metadata": {},
      "object": "earning_rule"
    },
    {
      "id": "lern_128f5834b30c4bf7a3",
      "name": "SummerPaid",
      "metadata": {},
      "object": "earning_rule"
    },
    {
      "id": "lern_128f57ec40cc4bf762",
      "name": "Autumn Ethiopia",
      "metadata": {},
      "object": "earning_rule"
    },
    {
      "id": "lern_12cd26a685db3e63d8",
      "name": "Birthday in more than 90 days",
      "metadata": {},
      "object": "earning_rule"
    }
  ],
  "memberships": [
    {
      "member": {
        "id": "lmbr_128f962dbc8c4ba5dc",
        "customer_id": "cust_6onRrs4kCnvSVrTs5YtDPFBG",
        "program_id": "lprg_128f58429f4c4bf7b2",
        "metadata": {},
        "object": "member"
      },
      "program": {
        "id": "lprg_128f58429f4c4bf7b2",
        "name": "AnnualProgram",
        "metadata": {},
        "object": "program"
      },
      "cards": [
        {
          "card": {
            "id": "lcrd_128f962dbd8c4ba5e1",
            "card_definition_id": "lcdef_128f4a88414c4bed69",
            "card_type": "INDIVIDUAL",
            "code": "AnnualTime-7M7ShPGfme",
            "object": "card"
          },
          "points_estimation": 150,
          "earning_rules": [
            {
              "earning_rule": {
                "id": "lern_128f577bd4d47c8e12",
                "object": "earning_rule"
              },
              "points_estimation": 150,
              "object": "earning_rule_estimation"
            }
          ],
          "object": "card_estimation"
        },
        {
          "card": {
            "id": "lcrd_128f962dbd8c4ba5e0",
            "card_definition_id": "lcdef_128f49963c0c4becb7",
            "card_type": "INDIVIDUAL",
            "code": "AutumnTime-R02hVARx33",
            "object": "card"
          },
          "points_estimation": 10,
          "earning_rules": [
            {
              "earning_rule": {
                "id": "lern_128f5822398c4bf78f",
                "object": "earning_rule"
              },
              "points_estimation": 10,
              "object": "earning_rule_estimation"
            }
          ],
          "object": "card_estimation"
        },
        {
          "card": {
            "id": "lcrd_128f962dbd8c4ba5df",
            "card_definition_id": "lcdef_128f495f720c4bec8c",
            "card_type": "INDIVIDUAL",
            "code": "SummerTime-7z8dWawICd",
            "object": "card"
          },
          "points_estimation": 10,
          "earning_rules": [
            {
              "earning_rule": {
                "id": "lern_128f5834b30c4bf7a3",
                "object": "earning_rule"
              },
              "points_estimation": 10,
              "object": "earning_rule_estimation"
            }
          ],
          "object": "card_estimation"
        }
      ],
      "benefits": [
        {
          "benefit": {
            "id": "lben_128f4bba81947c8542",
            "name": "Coffee sample Ethiopia",
            "type": "MATERIAL",
            "object": "benefit"
          },
          "earning_rules": [
            {
              "earning_rule": {
                "id": "lern_128f57ec40cc4bf762",
                "object": "earning_rule"
              },
              "object": "earning_rule_estimation"
            },
            {
              "earning_rule": {
                "id": "lern_12cd26a685db3e63d8",
                "object": "earning_rule"
              },
              "object": "earning_rule_estimation"
            }
          ],
          "object": "benefit_estimation"
        }
      ],
      "object": "member_earnings_opportunity"
    }
  ],
  "object": "earnings_examine_result"
}

Authorizations

X-App-Id & X-App-TokenbearerAuth

X-App-Id · string · header · required

X-App-Token · string · header · required

Body

application/json

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 · Loyalties Examine Earning Rules Examine Request Body Trigger · object · required

Which trigger events to examine. With ALL, all trigger events are examined and specific must be null/absent. With SPECIFIC, specific is required.

Show child attributes

customer_identification · object · 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.

Show child attributes

customer_order_paid · Loyalties Examine Earning Rules Examine Request Body Customer Order Paid · object

Context for examining customer.order.paid earning rules.

Show child attributes

customer_segment_entered · Loyalties Examine Earning Rules Examine Request Body Customer Segment Entered · object

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.

Show child attributes

customer_custom_event · Loyalties Examine Earning Rules Examine Request Body Customer Custom Event · object

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.

Show child attributes

Response

200

application/json

Earning rules examination result. An empty memberships array means no active membership has earning rules for the examined trigger.

Response body schema for POST /v2/loyalties/examine/earning-rules.

event · string | null

Examined trigger event (e.g. customer.order.paid, customer.segment.entered, customer.custom_event). null when trigger.type is ALL.

customer · object

Customer reference in examine results.

Show child attributes

earning_rules · Loyalties Examine Earning Rules Examine Response Body Earning Rule Detail · object[]

Lists earning rules that produced a points or benefit estimation, deduplicated across memberships.

Show child attributes

memberships · Loyalties Examine Earning Rules Examine Response Body Membership · object[]

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.

Show child attributes

object · string

Object type marker. Always earnings_examine_result.

Allowed value: "earnings_examine_result"