Integrate loyalty v2

To integrate Voucherify’s loyalty v2 with your platform, you’ll need to complete several steps. You’ll have to prepare your customer data, build the loyalty program with required modules, and create the loyalty member journey. Loyalty v2 has a modular structure, so you can start small and scale your program up as it grows with your members. The modular structure also helps you to optimize your loyalty program with your other incentives, like discount coupons or gift cards.

Preparation

Prepare your Voucherify account for a functional loyalty v2 integration.

Prepare the project

Prepare your test environment in Voucherify, for example the Sandbox project.Use an existing API key/token or create a new pair. Go to Project settings > Application keys to get X-App-Id and X-App-Token. Keep these keys on the server side only. See Authentication and Security.Make sure the API key can call loyalty, campaign, voucher, customer, product, and order endpoints used by your integration.Choose the correct regional API base URL from API overview (Europe, United States, or Asia).

Create loyalty v2 program

User guidesFollow Tutorial – Create basic program for a step-by-step dashboard setup. Read the Loyalty v2 overview for the program model and rollout context.

Create the loyalty v2 program by going to Loyalty hub > Programs.Design there the program architecture. You can start with a small program for earning and spending points. The required components are the point wallet (card definition) and an earning rule.Copy your v2 program ID (lprg_...). This is required for all member-related API calls.Set the program status to ACTIVE.

Once the program is active, you can experiment with additional earning rules, benefits, and rewards. However, you can’t add or edit point wallets or add tier structures.

Customer data

Your loyalty program members must first exist as customers in Voucherify to have a Voucherify customer ID (cust_...).You can:

Import your customer base with the Customer import or POST Import and Update Customers using CSV API endpoint.
Use a CDP or CRM tool to synchronize your customers with Voucherify.

Product data

If you plan to use products as loyalty program rewards, you have to create them in Voucherify first.You can:

Import your product database with the Product import in the Voucherify dashboard.
Use the API with POST Import Products using CSV and POST Update products in bulk endpoints.

Data schemas: Metadata and custom events

If you’re going to combine the loyalty v2 program with metadata (custom attributes for point wallets, loyalty members, and more) or custom events (for example, to trigger when points are earned), you’ll have to create relevant schemas.Read more about creating metadata schemas and custom events.

Acquisition

Use the POST Create member or POST Create member in batch (asynchronous action) with the Voucherify customer ID to add the customer as a member to a loyalty v2 program. By default, the customer is added as an ACTIVE member, who can immediately earn points and fully participate in the loyalty program. Optionally, you can add the customer as an INACTIVE member. An inactive member will have to be activated later with the POST Activate member endpoint to participate in the loyalty program.

{
    "customer_id": "cust_V0uCh3r1fyId"
}

{
    "customer_id": "cust_V0uCh3r1fyId",
    "status": "INACTIVE"
}

[
  {
    "customer_id": "cust_V0uCh3r1fyId01"
  },
  {
    "customer_id": "cust_V0uCh3r1fyId02"
  },
  {
    "customer_id": "cust_V0uCh3r1fyId03"
  }
]

The response for creating an individual member will return (see the lines in the example below):

Loyalty program member ID with a unique member ID (lmbr_...) (line 2).
The loyalty card(s) generated for the member with a unique loyalty card ID (lcrd_...) and the card definition (point wallet) ID. If your program uses multiple point wallets, the member will automatically receive a separate card for each card definition (cards[].card.id and cards[].card.card_definition_id in lines 16, 17, 54, and 55).

The response for creating a batch of new members returns an ID of an asynchronous action. Use the ID in the GET Get async action endpoint to check the processing status of the action.

Handle loyalty card code latencyMake sure your UI can handle null for the cards[].card.code property. The code property is generated asynchronously after member creation (lines 19 and 57).

In this response example, the loyalty program member receives two loyalty cards for two separate point wallets (card definitions).

{
    "id": "lmbr_V0uCh3r1fyId1",
    "customer_id": "cust_V0uCh3r1fyId2",
    "program_id": "lprg_V0uCh3r1fyId3",
    "status": "ACTIVE",
    "metadata": {},
    "created_at": "2026-06-06T06:06:06.006Z",
    "updated_at": null,
    "object": "member",
    "cards": [
        {
            "member_role": "OWNER",
            "created_at": "2026-06-06T06:06:06.006Z",
            "tier_progress": null,
            "card": {
                "id": "lcrd_V0uCh3r1fyId4",
                "card_definition_id": "lcdef_V0uCh3r1fyId5",
                "card_type": "INDIVIDUAL",
                "code": null,
                "lifetime_bucket": {
                    "points": {
                        "total": 0,
                        "earned": 0,
                        "added": 0,
                        "subtracted": 0,
                        "expired": 0,
                        "spent": 0,
                        "refunded": 0,
                        "returned": 0,
                        "locked": 0,
                        "unlocked": 0
                    },
                    "pending_points": {
                        "total": 0,
                        "activated": 0,
                        "canceled": 0
                    }
                },
                "balance": {
                    "points": 0,
                    "pending_points": 0
                },
                "next_expiration": null,
                "next_activation": null,
                "object": "card"
            },
            "object": "member_card"
        },
        {
            "member_role": "OWNER",
            "created_at": "2026-06-06T06:06:06.006Z",
            "tier_progress": null,
            "card": {
                "id": "lcrd_V0uCh3r1fyId6",
                "card_definition_id": "lcdef_V0uCh3r1fyId7",
                "card_type": "INDIVIDUAL",
                "code": null,
                "lifetime_bucket": {
                    "points": {
                        "total": 0,
                        "earned": 0,
                        "added": 0,
                        "subtracted": 0,
                        "expired": 0,
                        "spent": 0,
                        "refunded": 0,
                        "returned": 0,
                        "locked": 0,
                        "unlocked": 0
                    },
                    "pending_points": {
                        "total": 0,
                        "activated": 0,
                        "canceled": 0
                    }
                },
                "balance": {
                    "points": 0,
                    "pending_points": 0
                },
                "next_expiration": null,
                "next_activation": null,
                "object": "card"
            },
            "object": "member_card"
        }
    ]
}

{
  "async_action_id": "aa_abc123def456"
}

Discovery

Once you enroll your members, use the following endpoints so the members can learn more about your loyalty program: How they can earn and spend their points.

Examine earning rules

Use the POST Examine earning rules endpoint to estimate how many points a customer will earn in a given scenario. This simulation calculates the precise number of points and material or digital benefits a customer can earn based on specific operational business triggers. Because this evaluation is a dry-run execution, Voucherify calculates these opportunities dynamically without writing transactions to card balances or modifying customer states.

The POST Examine earning rules endpoint is an estimation of points to be earned. It doesn’t take into account additional earning rule triggers that may occur. For example, this can happen when a member pays for an order, earns points, and reaches a higher loyalty tier that will trigger additional points.

You can configure the simulation engine using two distinct trigger modes:

ALL mode: Simulates a parallel “what-if” scenario across all active earning rule configurations simultaneously.
SPECIFIC mode: Limits evaluation to one event context, like order paid, segment entered, or custom event.

ALL trigger

Use the trigger type ALL mode to create “Ways to earn” loyalty portals or customer dashboards. This option displays all available marketing paths to your customer simultaneously. When you pass the type ALL, Voucherify sets the top-level event parameter value to null (response line 2). Voucherify processes every earning rule active within the customer’s program. The simulation lists all earning rules (in the response example, the earning_rules array in lines 9–40) across distinct card definitions (the memberships[].cards array in lines 56–128, loyalty cards with names AnnualTime, AutumnTime, SummerTime). The response displays the total number of points to be earned on a card (points_estimation in line 65) and for individual earning rules that trigger the earning (points_estimation in lines 72 and 80). Voucherify also lists material rewards, such as the “Coffee sample Ethiopia” item, which is a MATERIAL benefit type (benefits[].benefit in lines 130–136).

Order paid earning rules with proportional calculationTo return an estimation for order paid earning rules which calculate points proportionally, you need to pass the customer_order_paid object with required data, like order.items array.

{
    "trigger": {
        "type": "ALL"
    },
    "customer_identification": {
        "type": "member_id",
        "member_id": "lmbr_128f962dbc8c4ba5dc"
    },
    "customer_order_paid": {
        "order": {
            "items": [
                {
                    "quantity": 1,
                    "price": 1000,
                    "amount": 1000,
                    "source_id": "vchrf-trckr-cp",
                    "name": "Voucherify trucker cap",
                    "related_object": "product",
                    "product": {
                        "metadata": {
                            "brand": "Voucherify",
                            "colour": "cobalt",
                            "category": "cap"
                        }
                    }
                },
                {
                    "quantity": 1,
                    "price": 15000,
                    "amount": 15000,
                    "source_id": "vchrf-tshrt",
                    "name": "Voucherify T-shirt",
                    "related_object": "product",
                    "product": {
                        "metadata": {
                            "brand": "Voucherify",
                            "colour": "ultramarine",
                            "category": "t-shirt"
                        }
                    }
                },
                {
                    "quantity": 1,
                    "price": 6500,
                    "amount": 6500,
                    "source_id": "vchrf-hd",
                    "name": "Voucherify hoodie",
                    "related_object": "product",
                    "product": {
                        "metadata": {
                            "brand": "Voucherify",
                            "colour": "regal crimson",
                            "category": "hoodie"
                        }
                    }
                },
                {
                    "quantity": 2,
                    "price": 1500,
                    "amount": 3000,
                    "source_id": "vchrf-vncnt-plsh",
                    "name": "Voucherify Vincent plushie",
                    "related_object": "product",
                    "product": {
                        "metadata": {
                            "brand": "Voucherify",
                            "colour": "cobalt",
                            "category": "plushie"
                        }
                    }
                }
            ]
        }
    },
    "customer_segment_entered": {
        "customer": {
            "metadata": {
                "VIP": false
            }
        }
    },
    "customer_custom_event": {
        "type": "SPECIFIC",
        "all": null,
        "specific": {
            "custom_event": {
                "schema_id": "ms_oX8au6DostTnHdWBAVVFnTLP"
            }
        }
    }
}

{
    "event": null,
    "customer": {
        "id": "cust_6onRrs4kCnvSVrTs5YtDPFBG",
        "source_id": "lx-rdmptr",
        "metadata": {},
        "object": "customer"
    },
    "earning_rules": [
        {
            "id": "lern_128f48ee44cc4bec34",
            "name": "EarningRule-OrderPaid",
            "metadata": {},
            "object": "earning_rule"
        },
        {
            "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"
        }
    ],
    "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": 25650,
                    "earning_rules": [
                        {
                            "earning_rule": {
                                "id": "lern_128f48ee44cc4bec34",
                                "object": "earning_rule"
                            },
                            "points_estimation": 25500,
                            "object": "earning_rule_estimation"
                        },
                        {
                            "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": "linc_128f4bba81947c8542",
                        "name": "Coffee sample Ethiopia",
                        "type": "MATERIAL",
                        "object": "benefit"
                    },
                    "earning_rules": [
                        {
                            "earning_rule": {
                                "id": "lern_128f57ec40cc4bf762",
                                "object": "earning_rule"
                            },
                            "object": "earning_rule_estimation"
                        }
                    ],
                    "object": "benefit_estimation"
                }
            ],
            "object": "member_earnings_opportunity"
        }
    ],
    "object": "earnings_examine_result"
}

SPECIFIC trigger: Order paid

Use the SPECIFIC trigger type customer.order.paid inside digital shopping carts to estimate customer point collection right before final billing. The simulation isolates rules linked directly to PAID transaction states. Voucherify processes the order details from your request context, including items, metadata, catalog categories, and amount values. In the example, Voucherify resolves the EarningRule-OrderPaid rule (response example, earning_rules array, first object in lines 10–15) and returns an explicit balance projection of 25500 points for the primary AnnualTime loyalty card (memberships[].cards[].points_estimation in line 53). Also, the response lists earnings for AutumnPaid and SummerPaid earning rules (earning_rules array, objects in lines 16–27) that are used for the AutumnTime and SummerTime loyalty cards (memberships[].cards[].points_estimation in lines 74 and 95). The calculation reflects the current shopping cart properties without adding points to the active card yet.

{
    "trigger": {
        "type": "SPECIFIC",
        "specific": {
            "event": "customer.order.paid"
        }
    },
    "customer_identification": {
        "type": "member_id",
        "member_id": "lmbr_128f962dbc8c4ba5dc"
    },
    "customer_order_paid": {
        "order": {
            "items": [
                {
                    "quantity": 1,
                    "price": 1000,
                    "amount": 1000,
                    "source_id": "vchrf-trckr-cp",
                    "name": "Voucherify trucker cap",
                    "related_object": "product",
                    "product": {
                        "metadata": {
                            "brand": "Voucherify",
                            "colour": "cobalt",
                            "category": "cap"
                        }
                    }
                },
                {
                    "quantity": 1,
                    "price": 15000,
                    "amount": 15000,
                    "source_id": "vchrf-tshrt",
                    "name": "Voucherify T-shirt",
                    "related_object": "product",
                    "product": {
                        "metadata": {
                            "brand": "Voucherify",
                            "colour": "ultramarine",
                            "category": "t-shirt"
                        }
                    }
                },
                {
                    "quantity": 1,
                    "price": 6500,
                    "amount": 6500,
                    "source_id": "vchrf-hd",
                    "name": "Voucherify hoodie",
                    "related_object": "product",
                    "product": {
                        "metadata": {
                            "brand": "Voucherify",
                            "colour": "regal crimson",
                            "category": "hoodie"
                        }
                    }
                },
                {
                    "quantity": 2,
                    "price": 1500,
                    "amount": 3000,
                    "source_id": "vchrf-vncnt-plsh",
                    "name": "Voucherify Vincent plushie",
                    "related_object": "product",
                    "product": {
                        "metadata": {
                            "brand": "Voucherify",
                            "colour": "cobalt",
                            "category": "plushie"
                        }
                    }
                }
            ]
        }
    }
}

{
    "event": "customer.order.paid",
    "customer": {
        "id": "cust_6onRrs4kCnvSVrTs5YtDPFBG",
        "source_id": "lx-rdmptr",
        "metadata": {},
        "object": "customer"
    },
    "earning_rules": [
        {
            "id": "lern_128f48ee44cc4bec34",
            "name": "EarningRule-OrderPaid",
            "metadata": {},
            "object": "earning_rule"
        },
        {
            "id": "lern_128f5822398c4bf78f",
            "name": "AutumnPaid",
            "metadata": {},
            "object": "earning_rule"
        },
        {
            "id": "lern_128f5834b30c4bf7a3",
            "name": "SummerPaid",
            "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": 25500,
                    "earning_rules": [
                        {
                            "earning_rule": {
                                "id": "lern_128f48ee44cc4bec34",
                                "object": "earning_rule"
                            },
                            "points_estimation": 25500,
                            "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": [],
            "object": "member_earnings_opportunity"
        }
    ],
    "object": "earnings_examine_result"
}

SPECIFIC trigger: Customer entered segment

Prerequisite: Customer segmentThis scenario requires an earning rule that uses a customer segment as a trigger.Read the Customer segments guide to learn more about customer segments.

Use the SPECIFIC trigger type customer.segment.entered to forecast reward outcomes when a member moves into a high-tier profile segment, like a VIP club. You can display this as an achievable milestone in the member profile. The evaluation matches metadata configurations in the customer reference object. In this case, passing the metadata key-value pair "VIP": true simulates a segment transition (request example, customer_segment_entered.customer.metadata in line 15). Voucherify identifies the EnterVipSegment rule schema (response example, the earning_rules array, first object in lines 12–17). The response isolates the member’s AnnualTime loyalty card and lists a milestone award valuation of 150 points (memberships[].cards[].points_estimation in line 43). Other purchase-dependent rules are omitted from the calculation automatically.

{
    "trigger": {
        "type": "SPECIFIC",
        "specific": {
            "event": "customer.segment.entered"
        }
    },
    "customer_identification": {
        "type": "member_id",
        "member_id": "lmbr_128f962dbc8c4ba5dc"
    },
    "customer_segment_entered": {
        "customer": {
            "metadata": {
                "VIP": true
            }
        }
    }
}

{
    "event": "customer.segment.entered",
    "customer": {
        "id": "cust_6onRrs4kCnvSVrTs5YtDPFBG",
        "source_id": "lx-rdmptr",
        "metadata": {
            "VIP": true
        },
        "object": "customer"
    },
    "earning_rules": [
        {
            "id": "lern_128f577bd4d47c8e12",
            "name": "EnterVipSegment",
            "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"
                }
            ],
            "benefits": [],
            "object": "member_earnings_opportunity"
        }
    ],
    "object": "earnings_examine_result"
}

SPECIFIC trigger: Custom event

Prerequisite: Custom event schemaThis scenario requires an earning rule that uses a custom event as a trigger.Read the Custom events guide to learn more about custom events.

Use the SPECIFIC trigger type customer.custom_event to evaluate custom behaviors outside standard purchase workflows, such as writing product reviews, bringing reusable cups to a coffee shop, or using mobile apps. The calculation evaluates rules that trigger on unique business schemas rather than order parameters or segment fields. The custom event is passed as a schema_id inside the customer_custom_event object (request example, customer_custom_event.specific.custom_event.schema_id in line 16). In the example below, the earning rule (response example, the object in the earning_rules array, lines 10–15) awards a benefit rather than loyalty points on a card. As a result, the simulation bypasses regular point cards completely, meaning the cards array returns empty (line 32). Instead, the response fills the benefits array, which shows that once this action is completed, the member will receive the “Coffee sample Ethiopia” product (lines 34–40).

”ALL” type for custom eventsIn the customer_custom_event you can pass "type": "ALL" to return a point estimation for all earning rules that are based on custom events. Use this type if your program runs many earnings that trigger when a member performs an action based on a custom event.

{
    "trigger": {
        "type": "SPECIFIC",
        "specific": {
            "event": "customer.custom_event"
        }
    },
    "customer_identification": {
        "type": "member_id",
        "member_id": "lmbr_128f962dbc8c4ba5dc"
    },
    "customer_custom_event": {
        "type": "SPECIFIC",
        "specific": {
            "custom_event": {
                "schema_id": "ms_oX8au6DostTnHdWBAVVFnTLP"
            }
        }
    }
}

{
    "event": "customer.custom_event",
    "customer": {
        "id": "cust_6onRrs4kCnvSVrTs5YtDPFBG",
        "source_id": "lx-rdmptr",
        "metadata": {},
        "object": "customer"
    },
    "earning_rules": [
        {
            "id": "lern_128f57ec40cc4bf762",
            "name": "Autumn Ethiopia",
            "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": [],
            "benefits": [
                {
                    "benefit": {
                        "id": "linc_128f4bba81947c8542",
                        "name": "Coffee sample Ethiopia",
                        "type": "MATERIAL",
                        "object": "benefit"
                    },
                    "earning_rules": [
                        {
                            "earning_rule": {
                                "id": "lern_128f57ec40cc4bf762",
                                "object": "earning_rule"
                            },
                            "object": "earning_rule_estimation"
                        }
                    ],
                    "object": "benefit_estimation"
                }
            ],
            "object": "member_earnings_opportunity"
        }
    ],
    "object": "earnings_examine_result"
}

Examine rewards

Prerequisite: Create and add rewards to point walletsCreated rewards must be added to relevant point wallets to be redeemable by your members. When you add the reward to a point wallet, you also define its price in points.You can create rewards through the dashboard or the API.

Use the POST Examine rewards endpoint to verify which benefits, digital discount coupons or gift card credits, and material rewards are available to a member across their active loyalty program memberships. This simulation calculates the precise point costs using specific spending rules and evaluates stock availability in real time. Because this evaluation is a dry-run execution, the Voucherify engine processes these opportunities without writing transactions to card balances. You can use this endpoint in your user interface to build dynamic reward catalogs or member portals that show customers exactly what rewards they can unlock with their current point balance, as well as the specific actions required to unlock restricted rewards. The Voucherify simulation engine evaluates every reward assignment and classifies the reward under one of two distinct operational states within the rewards array. The endpoint returns only active rewards (response example, lines 8–30) and draft rewards are ignored.

AVAILABLE status

When a reward returns an AVAILABLE status, the loyalty program member meets all eligibility criteria for reward redemption. This status guarantees that:

The member has an active loyalty card belonging to the required card definition.
The current point balance on that specific loyalty card is equal to or greater than the resolved point cost.
The reward assignment has sufficient stock and is currently active.

In the response example below, the loyalty card AnnualTime-7M7ShPGfme contains two AVAILABLE reward opportunities: the “Free item coupon” (requiring 300 points; the memberships[].cards[].card.rewards object lines 91–102) and the “Minas Gerais 500” material reward (requiring 150 points; the memberships[].cards[].card.rewards object in lines 103–114).

UNAVAILABLE status

When a reward returns an UNAVAILABLE status, the member can’t redeem it at that moment. To prevent integration guesswork and support frontend user guidance, the Voucherify API provides a structured unavailability_reasons array detailing the exact failure point. The evaluation engine identifies five primary reasons for reward unavailability:

insufficient_balance: The loyalty card balance is lower than the required reward cost. The API returns explicit context in the details object showing required, available, and missing point values.
out_of_stock: The reward assignment stock is depleted.
no_matching_cost: No applicable point cost configuration is found or the cost configuration is locked.
no_card_for_cost: The member profile lacks an active card for the required card definition.
reward_inactive: The parent reward object is paused or inactive.

In the response example below, the “Carioca cap” reward on the loyalty card SummerTime-7z8dWawICd is marked UNAVAILABLE (line 61) due to insufficient_balance because the member possesses only 50 points out of the required 250 points (the memberships[].cards[].card.rewards.unavailability_reasons object in lines 66–75).

UX best practiceUse the missing property inside the insufficient_balance details object to calculate and display progress bars or “points needed” callouts directly on your e-commerce checkout page or mobile application.

Examine rewards: Example request and response

Check the following request and response payloads to learn how AVAILABLE and UNAVAILABLE rewards are returned.

{
    "customer_identification": {
        "type": "member_id",
        "member_id": "lmbr_128f962dbc8c4ba5dc"
    }
}

{
    "customer": {
        "id": "cust_6onRrs4kCnvSVrTs5YtDPFBG",
        "source_id": "lx-rdmptr",
        "metadata": {},
        "object": "customer"
    },
    "rewards": [
        {
            "id": "lrew_128f4cefbad47c863e",
            "name": "Carioca cap",
            "type": "MATERIAL",
            "metadata": {},
            "object": "reward"
        },
        {
            "id": "lrew_128f4cab04147c8608",
            "name": "Free item coupon",
            "type": "DIGITAL",
            "metadata": {},
            "object": "reward"
        },
        {
            "id": "lrew_128f4c6710947c85d1",
            "name": "Minas Gerais 500",
            "type": "MATERIAL",
            "metadata": {},
            "object": "reward"
        }
    ],
    "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_128f962dbd8c4ba5df",
                        "card_definition_id": "lcdef_128f495f720c4bec8c",
                        "card_type": "INDIVIDUAL",
                        "code": "SummerTime-7z8dWawICd",
                        "object": "card"
                    },
                    "rewards": [
                        {
                            "reward": {
                                "id": "lrew_128f4cefbad47c863e",
                                "object": "reward"
                            },
                            "status": "UNAVAILABLE",
                            "cost": {
                                "points": 250,
                                "object": "reward_cost"
                            },
                            "unavailability_reasons": [
                                {
                                    "reason": "insufficient_balance",
                                    "details": {
                                        "required": 250,
                                        "available": 50,
                                        "missing": 200
                                    },
                                    "object": "reward_unavailability_reason"
                                }
                            ],
                            "object": "reward_estimation"
                        }
                    ],
                    "object": "card_estimation"
                },
                {
                    "card": {
                        "id": "lcrd_128f962dbd8c4ba5e1",
                        "card_definition_id": "lcdef_128f4a88414c4bed69",
                        "card_type": "INDIVIDUAL",
                        "code": "AnnualTime-7M7ShPGfme",
                        "object": "card"
                    },
                    "rewards": [
                        {
                            "reward": {
                                "id": "lrew_128f4cab04147c8608",
                                "object": "reward"
                            },
                            "status": "AVAILABLE",
                            "cost": {
                                "points": 300,
                                "object": "reward_cost"
                            },
                            "object": "reward_estimation"
                        },
                        {
                            "reward": {
                                "id": "lrew_128f4c6710947c85d1",
                                "object": "reward"
                            },
                            "status": "AVAILABLE",
                            "cost": {
                                "points": 150,
                                "object": "reward_cost"
                            },
                            "object": "reward_estimation"
                        }
                    ],
                    "object": "card_estimation"
                }
            ],
            "object": "member_rewards_opportunity"
        }
    ],
    "object": "rewards_examine_result"
}

Activity

Your customers need to perform activities to meet earning rules and earn points or other benefits.

Create order

If your customers earn points or benefits when they finalize transaction in your system (customer.order.paid event), Voucherify relies on the condition that the POST Create order request has the status field set to PAID. When the Order API processes a payload with status set to PAID (line 3), the loyalty engine evaluates the line items and order amount to add points or benefits. Submitting orders with other statuses (such as CREATED or FULFILLED) will fail to activate the earnings.

Order paid request payload

{
    "source_id": "coffee_order_77129",
    "status": "PAID",
    "amount": 3500,
    "customer": {
      "source_id": "cust_espresso_fan_99",
      "email": "customer@coffeeclub.com"
    },
    "items": [
      {
        "source_id": "prod_colombian_supremo_1kg",
        "related_object": "product",
        "quantity": 1,
        "price": 3500,
        "amount": 3500,
        "product": {
          "name": "Colombian Supremo Coffee Beans",
          "metadata": {
            "roast": "medium",
            "origin": "Colombia"
          }
        }
      }
    ]
}

Custom events

If your members earn points or benefits when performing specific custom activities, like subscribing to a newsletter, leaving a review, or unlocking a daily perk, use the POST Track custom event endpoint (/v1/events). The request payload must include:

customer.id and/or customer.source_id (lines 3 and 4) to link the event to a specific customer in Voucherify database. The customer must be a member in the loyalty program.
Name of the custom event that triggers the earning rule passed as the value of the event property (line 6).

{
    "customer": {
        "id": "cust_6onRrs4kCnvSVrTs5YtDPFBG",
        "source_id": "lx-rdmptr"
    },
    "event": "example_custom_event_name"
}

When Voucherify registers the custom event, the earning rule will trigger and issue points or benefit to the member as defined in its earnings.

Enter segment

Read the Customer segments article to learn more about customer segments and how to create them.

If your members earn points or benefits when they join a segment of VIP customers, for example, you don’t have to send any specific API requests. The earning rule triggers automatically when Voucherify registers the member has joined the defined dynamic customer segment.

Customer segment suggestionsYou can define segments on the basis of various customer properties, like total amount of all orders, birth date, or your own custom attributes (metadata). Here are some ideas for customer segments:

Customers who haven’t placed an order for more than 90 days.
Customers who have birthday today.
VIP customers who spent more than $1000 USD in your store.
Customers with a defined metadata "pet_owner": true.
Customers who performed an activity “Collect June badge” defined as a custom event less than 5 days ago.

Retention

Use the following endpoints and data to build a member profile view, which helps retaining your member base and keeps them engaged.

Get program membership

Use the GET program membership endpoint (GET /v2/loyalties/programs/{programId}/memberships/{customerId}?identification_type=member_id) to create a member profile that will show:

The member’s identity and status in the program.
All loyalty cards the member has in the program.
Current point balance, pending points, and other life time point data.
Dates for point expiration and activation.
Current progress in the tier structure.

The response is a membership object that groups three top-level fields:

member: The member’s profile in the program (lines 3–10).
program: A summary of the loyalty program the member belongs to (lines 13–17). This is useful when your integration handles several programs and needs to identify the program referred to in the response.
cards: The list of loyalty cards issued to the member (starting at line 19), used to render points and tier progress.

Similar endpointsThe Get membership endpoint works in a similar way to Get member. Get member returns member details in the context of a loyalty program. It uses only the member ID as the path parameter and it doesn’t return tier_progress data.If your program runs loyalty tiers, use the Get membership endpoint.Check the documentation of these endpoints to learn more about their differences and similarities.

The response example is used in the Member, Points, and Tiers sections below.

Get membership response

{
    "member": {
        "id": "lmbr_128f962dbc8c4ba5dc",
        "customer_id": "cust_6onRrs4kCnvSVrTs5YtDPFBG",
        "program_id": "lprg_128f58429f4c4bf7b2",
        "status": "ACTIVE",
        "metadata": {},
        "created_at": "2026-06-11T15:59:41.298Z",
        "updated_at": null,
        "object": "member"
    },
    "program": {
        "id": "lprg_128f58429f4c4bf7b2",
        "name": "AnnualProgram",
        "status": "ACTIVE",
        "metadata": {},
        "object": "program"
    },
    "cards": [
        {
            "member_role": "OWNER",
            "created_at": "2026-06-11T15:59:41.303Z",
            "card": {
                "id": "lcrd_128f962dbd8c4ba5df",
                "card_definition_id": "lcdef_128f495f720c4bec8c",
                "card_type": "INDIVIDUAL",
                "code": "SummerTime-7z8dWawICd",
                "lifetime_bucket": {
                    "points": {
                        "total": 740,
                        "earned": 40,
                        "added": 700,
                        "purchased": 0,
                        "purchased_reversed": 0,
                        "subtracted": 30,
                        "expired": 300,
                        "spent": 250,
                        "refunded": 0,
                        "returned": 0,
                        "locked": 250,
                        "unlocked": 250
                    },
                    "pending_points": {
                        "total": 50,
                        "activated": 40,
                        "canceled": 0
                    }
                },
                "balance": {
                    "points": 160,
                    "pending_points": 10
                },
                "next_expiration": {
                    "points": 160,
                    "date": "2026-08-08"
                },
                "next_activation": {
                    "points": 10,
                    "type": "PERIOD_BASED",
                    "date": "2026-07-20"
                },
                "object": "card"
            },
            "object": "member_card"
        },
        {
            "member_role": "OWNER",
            "created_at": "2026-06-11T15:59:41.303Z",
            "card": {
                "id": "lcrd_128f962dbd8c4ba5e0",
                "card_definition_id": "lcdef_128f49963c0c4becb7",
                "card_type": "INDIVIDUAL",
                "code": "AutumnTime-R02hVARx33",
                "lifetime_bucket": {
                    "points": {
                        "total": 50,
                        "earned": 0,
                        "added": 50,
                        "purchased": 0,
                        "purchased_reversed": 0,
                        "subtracted": 0,
                        "expired": 0,
                        "spent": 0,
                        "refunded": 0,
                        "returned": 0,
                        "locked": 0,
                        "unlocked": 0
                    },
                    "pending_points": {
                        "total": 50,
                        "activated": 0,
                        "canceled": 0
                    }
                },
                "balance": {
                    "points": 50,
                    "pending_points": 50
                },
                "next_expiration": {
                    "points": 50,
                    "date": "2026-12-23"
                },
                "next_activation": {
                    "points": 50,
                    "type": "FIXED_DATES",
                    "date": "2026-12-23"
                },
                "object": "card"
            },
            "object": "member_card"
        },
        {
            "member_role": "OWNER",
            "created_at": "2026-06-11T15:59:41.303Z",
            "tier_progress": {
                "current": {
                    "id": "lt_128f4b46400c4bedfb",
                    "name": "Bronze",
                    "activated_at": "2026-07-13T17:22:22.626Z",
                    "expires_at": null,
                    "points": {
                        "current": 0,
                        "min": 0,
                        "max": 99
                    }
                },
                "deferred": [],
                "tier_structure": {
                    "id": "lts_128f4b460e4c4bedf6",
                    "object": "tier_structure"
                },
                "risks": [],
                "opportunities": [
                    {
                        "valid_until": null,
                        "tier_id": "lt_128f4b46558c4bedff",
                        "points": 100
                    },
                    {
                        "valid_until": null,
                        "tier_id": "lt_128f4b466a0c4bee03",
                        "points": 200
                    },
                    {
                        "valid_until": null,
                        "tier_id": "lt_128f4b46808c4bee07",
                        "points": 300
                    }
                ],
                "object": "member_tier_progress"
            },
            "card": {
                "id": "lcrd_128f962dbd8c4ba5e1",
                "card_definition_id": "lcdef_128f4a88414c4bed69",
                "card_type": "INDIVIDUAL",
                "code": "AnnualTime-7M7ShPGfme",
                "lifetime_bucket": {
                    "points": {
                        "total": 1250,
                        "earned": 250,
                        "added": 1000,
                        "purchased": 0,
                        "purchased_reversed": 0,
                        "subtracted": 1000,
                        "expired": 0,
                        "spent": 150,
                        "refunded": 0,
                        "returned": 0,
                        "locked": 10,
                        "unlocked": 10
                    },
                    "pending_points": {
                        "total": 300,
                        "activated": 250,
                        "canceled": 0
                    }
                },
                "balance": {
                    "points": 100,
                    "pending_points": 50
                },
                "next_expiration": null,
                "next_activation": {
                    "points": 50,
                    "type": "PERIOD_BASED",
                    "date": "2026-07-20"
                },
                "object": "card"
            },
            "object": "member_card"
        }
    ],
    "object": "membership"
}

Member

The member object (lines 2–11 of the response above) holds the profile data you use to identify the member in your system and reflect their status in the program:

id: The loyalty member ID assigned by Voucherify (line 3). Store it alongside your own customer record and pass it back on subsequent calls to this endpoint.
customer_id: Links the member to a Voucherify customer (line 4), which you can use to correlate loyalty activity with the customer profile in your CRM.
program_id: Identifies the loyalty program the member belongs to (line 5). Combined with the top-level program object, this lets you support integrations that manage several programs at once.
status: Shows whether the member is ACTIVE or INACTIVE (line 6). Use it to gate loyalty features in your UI. For example, hide the “Redeem points” action for inactive members.
metadata: Returns any custom attributes you added to the member (line 7), such as an internal loyalty tier from another system or the enrollment channel.
created_at and updated_at are timestamps for when the member was created and last modified (lines 8, 9).

Points

With the Get membership endpoint you can create a member profile that lists points available to a member. Each of the member’s loyalty cards is returned in the cards array (starting at line 19). The details regarding points are stored in the following objects (referenced here from the first card, SummerTime-7z8dWawICd):

lifetime_bucket: Stores historical details regarding points and pending_points (lines 29–47). For example, you can use the data to show how many points were earned, spent, expired, and so on.
balance: Stores the details about the current number of available points (balance.points) for spending and the current number of pending_points (lines 50, 51).
next_expiration: Stores the details about the number of points that are about to expire and the nearest date (lines 54, 55). If you configured point expiration, you can use this data to nudge your members to spend the points before they expire.
next_activation: Stores the details about the date and number of points that are about to be activated from the pending state as well as the type of the activation (lines 58–60).

Tiers

If your program runs loyalty tiers, you can also use the Get membership endpoint to return the details about the current tier progress for a given loyalty card. Use the data from the tier_progress object on the relevant card in the cards array (lines 115–151 of the response above, on the third card AnnualTime-7M7ShPGfme) to build a member profile that will display the active tier, and also risks and opportunities:

current: Returns the loyalty tier the member is currently on, including the tier ID, name, when the member achieved it and the point range (lines 116–126).
risks: Returns data for tier expiration and downgrade (line 132). In this example the array is empty, meaning the member is not scheduled to lose their current tier.
opportunities: Returns the number of points the member must earn to reach higher tiers (lines 133–149).

List transactions

Use the GET List transactions endpoint to extend the member profile in your system with details about all point movements on a member’s card. If your loyalty program uses several card definitions (point wallets), create a separate transaction list for each card that’s governed by a given wallet. The list card transactions endpoint lists many types (type) of transactions to match your business case. The transactions list the date of occurrence (created_at), number of points affected (points object), and other details. In a simple loyalty program, the key transactions types are:

POINTS_SPENT_ON_REWARD: Points spent to buy a reward. The details object lists the number of points and the reward.id (lines 11–24)
PENDING_POINTS_ACTIVATED: Points that were in a pending state, but they were activated manually or automatically as set in the card definition configuration (the details object in lines 38–47).
PENDING_POINTS_ADDED: Pending points that were added to the loyalty card under the point wallet settings (the details object in lines 61–76).
POINTS_EXPIRED: Points that expired under the card definition settings (the details object in lines 90–108).
POINTS_EARNED: Points earned and instantly added to the loyalty card (the details object in the Point earned example, line 11–24).

{
    "data": [
        {
            "id": "lctx_129748dbafe65ae86d",
            "card_id": "lcrd_128f962dbd8c4ba5e1",
            "program_id": "lprg_128f58429f4c4bf7b2",
            "member_id": "lmbr_128f962dbc8c4ba5dc",
            "card_definition_id": "lcdef_128f4a88414c4bed69",
            "card_type": "INDIVIDUAL",
            "type": "POINTS_SPENT_ON_REWARD",
            "details": {
                "reason": "Points spent on reward",
                "rejection": null,
                "metadata": {},
                "points": {
                    "total": 150
                },
                "reward": {
                    "id": "lrew_128f4c6710947c85d1"
                },
                "reward_transaction": {
                    "id": "lrtx_129748dbafe65ae86e"
                }
            },
            "status": "APPROVED",
            "created_at": "2026-06-17T15:29:43.104Z",
            "updated_at": "2026-06-17T15:29:45.622Z",
            "object": "card_transaction"
        },
        {
            "id": "lctx_128f9a03c6cc4ba8e7",
            "card_id": "lcrd_128f962dbd8c4ba5e1",
            "program_id": "lprg_128f58429f4c4bf7b2",
            "member_id": "lmbr_128f962dbc8c4ba5dc",
            "card_definition_id": "lcdef_128f4a88414c4bed69",
            "card_type": "INDIVIDUAL",
            "type": "PENDING_POINTS_ACTIVATED",
            "details": {
                "reason": "Manual points activation",
                "rejection": null,
                "metadata": {},
                "points": {
                    "total": 400,
                    "date": "2026-06-21",
                    "type": "PERIOD_BASED"
                }
            },
            "status": "APPROVED",
            "created_at": "2026-06-11T16:16:26.907Z",
            "updated_at": "2026-06-11T16:16:27.291Z",
            "object": "card_transaction"
        },
        {
            "id": "lctx_128f9821be4fd14efd",
            "card_id": "lcrd_128f962dbd8c4ba5e1",
            "program_id": "lprg_128f58429f4c4bf7b2",
            "member_id": "lmbr_128f962dbc8c4ba5dc",
            "card_definition_id": "lcdef_128f4a88414c4bed69",
            "card_type": "INDIVIDUAL",
            "type": "PENDING_POINTS_ADDED",
            "details": {
                "reason": "AnnualProgram / EarningRule-OrderPaid",
                "rejection": null,
                "metadata": {
                    "event_id": "evcus_128f981fced47cbe9b",
                    "member_id": "lmbr_128f962dbc8c4ba5dc",
                    "program_id": "lprg_128f58429f4c4bf7b2",
                    "earning_item_id": "lernei_128f48ee3fcc4bec33",
                    "earning_rule_id": "lern_128f48ee44cc4bec34"
                },
                "points": {
                    "total": 400,
                    "date": "2026-06-21",
                    "type": "PERIOD_BASED"
                }
            },
            "status": "APPROVED",
            "created_at": "2026-06-11T16:08:13.305Z",
            "updated_at": "2026-06-11T16:08:14.170Z",
            "object": "card_transaction"
        },
        {
            "id": "lctx_129a515e9aa3f9dd93",
            "card_id": "lcrd_128f962dbd8c4ba5df",
            "program_id": "lprg_128f58429f4c4bf7b2",
            "member_id": "lmbr_128f962dbc8c4ba5dc",
            "card_definition_id": "lcdef_128f495f720c4bec8c",
            "card_type": "INDIVIDUAL",
            "type": "POINTS_EXPIRED",
            "details": {
                "reason": "Points expired automatically",
                "rejection": null,
                "metadata": {},
                "points": {
                    "total": 50
                },
                "date": "2026-06-09",
                "buckets": [
                    {
                        "id": "lcpeb_1299ec455b625c31e1",
                        "points": {
                            "total": 50
                        },
                        "expiration_date": "2026-06-09",
                        "expiration_type": "ROLLING_EXPIRATION"
                    }
                ]
            },
            "status": "APPROVED",
            "created_at": "2026-06-10T00:02:20.906Z",
            "updated_at": "2026-06-10T00:02:20.975Z",
            "object": "card_transaction"
        }
    ],
    "cursor": {
        "next": "lcrsctx_12989e71c62b6d5baf",
        "expires_at": "2026-06-18T16:32:07.896Z"
    },
    "object": "list"
}

{
    "data": [
        {
            "id": "lctx_1298a2ae5ba25c6454",
            "card_id": "lcrd_1298a287482b6d5e90",
            "program_id": "lprg_1298a2068ad09df2dc",
            "member_id": "lmbr_1298a28746eb6d5e8d",
            "card_definition_id": "lcdef_1298a22790509df2f8",
            "card_type": "INDIVIDUAL",
            "type": "POINTS_EARNED",
            "details": {
                "reason": "Pointexpire / EXPIRE_EARNING_RULE",
                "rejection": null,
                "metadata": {
                    "event_id": "evcus_1298a2abb06b6d5ec2",
                    "member_id": "lmbr_1298a28746eb6d5e8d",
                    "program_id": "lprg_1298a2068ad09df2dc",
                    "earning_item_id": "lernei_1298a23b9f509df311",
                    "earning_rule_id": "lern_1298a23baf509df312"
                },
                "points": {
                    "total": 50,
                    "expiration_date": "2026-06-19"
                }
            },
            "status": "APPROVED",
            "created_at": "2026-06-18T16:40:38.510Z",
            "updated_at": "2026-06-18T16:40:39.402Z",
            "object": "card_transaction"
        }
    ],
    "cursor": null,
    "object": "list"
}

List reward purchases

Use the GET List reward purchases endpoint to show your members the rewards they have purchased. This endpoint lists purchases for all cards the member has. The details (lines 12–33 and 47–68) object lists more information about the reward purchase, like the number of points spent or the reward type.

List reward purchases response

{
    "data": [
        {
            "id": "lrtx_1299a9ded817f57b90",
            "card_id": "lcrd_128f962dbd8c4ba5df",
            "card_transaction_id": "lctx_1299a9ded817f57b8f",
            "program_id": "lprg_128f58429f4c4bf7b2",
            "member_id": "lmbr_128f962dbc8c4ba5dc",
            "reward_id": "lrew_128f4cefbad47c863e",
            "status": "APPROVED",
            "type": "PURCHASE",
            "details": {
                "reason": "Points spent on reward",
                "rejection": null,
                "metadata": {},
                "points": {
                    "total": 250
                },
                "result": {
                    "reward": {
                        "id": "lrew_128f4cefbad47c863e",
                        "type": "MATERIAL"
                    },
                    "quantity": 1,
                    "material": {
                        "type": "PRODUCT",
                        "product": {
                            "id": "prod_128f4cd0a94c4bef25"
                        }
                    },
                    "digital": null
                }
            },
            "created_at": "2026-06-19T11:50:32.033Z",
            "updated_at": "2026-06-19T11:50:33.387Z",
            "object": "reward_transaction"
        },
        {
            "id": "lrtx_129748dbafe65ae86e",
            "card_id": "lcrd_128f962dbd8c4ba5e1",
            "card_transaction_id": "lctx_129748dbafe65ae86d",
            "program_id": "lprg_128f58429f4c4bf7b2",
            "member_id": "lmbr_128f962dbc8c4ba5dc",
            "reward_id": "lrew_128f4c6710947c85d1",
            "status": "APPROVED",
            "type": "PURCHASE",
            "details": {
                "reason": "Points spent on reward",
                "rejection": null,
                "metadata": {},
                "points": {
                    "total": 150
                },
                "result": {
                    "reward": {
                        "id": "lrew_128f4c6710947c85d1",
                        "type": "MATERIAL"
                    },
                    "quantity": 1,
                    "material": {
                        "type": "PRODUCT",
                        "product": {
                            "id": "prod_128f4c2edf547c859e"
                        }
                    },
                    "digital": null
                }
            },
            "created_at": "2026-06-17T15:29:43.104Z",
            "updated_at": "2026-06-17T15:29:44.542Z",
            "object": "reward_transaction"
        }
    ],
    "cursor": null,
    "object": "list"
}

Fulfillment

Your loyalty program needs a way for your members to spend the loyalty points they’ve earned. In a typical loyalty program, members can spend points to:

Use the points as currency to pay for their orders.
Purchase rewards.

Pay with points

Prerequisite: Settings of pay with points in the point walletThe point-to-currency exchange ratio is defined in the point wallet that governs the behavior of the loyalty card.

To allow your members to use points as currency and pay for their purchases, you’ll need two endpoints:

POST Create order to create an order in Voucherify.
POST Pay for an order with points to use the existing order ID in this endpoint.

Qualifying, validating, and redeeming incentivesIf you want to combine your loyalty program with qualification, validation, and redemption of incentives, these should happen before the POST Pay with points endpoint is used.If you use the redemption endpoint (POST v1/redemptions), it can create an order in Voucherify if an order object is passed. You can then skip the POST Create order endpoint, but you’ll need to retrieve the order ID from the v1/redemptions response.

The POST Pay for an order with points endpoint has:

Two required fields:
- The card_id string of the loyalty card (lcrd_...) whose points will be used in the transaction (line 2 in the examples).
- The order object that contains the id or source_id of the order to be paid (line 4).
Two optional fields:
- The mode string that defines if the request is used to simulate the transaction or to actually pay for the order (line 6). Pass the following values:
  - DRY_RUN to perform a simulation of the transaction. No points are spent from the member loyalty card and no transaction records are created.
  - TRANSACTION to create an actual transaction. Points are spent to lower the total amount of the order.
- The payment_limit object that defines a limit on the transaction by providing a type (line 6):
  - CARD_BALANCE: Default setting that allows the automatic payment up to the maximum of the total balance of the loyalty card. This setting is used when no payment_limit object is sent.
  - POINTS_LIMIT: Uses the points_limit object to define how many points will be spent in the transaction. In the example below, the amount to be spent equals 100 points (line 10). If the card has fewer points than the set value for max, all available points will be used.
  - AMOUNT_LIMIT: Uses the amount_limit object to define how much of the order amount can be paid for with points. The max value is defined in the smallest currency amount (line 10), so 100 means $1, for example.

See the request examples below.

    {
        "card_id": "lcrd_128f962dbd8c4ba5e1",
        "order": {
            "id": "ord_12b4cdf5f30c158825"
        },
        "mode": "TRANSACTION",
        "payment_limit": {
            "type": "CARD_BALANCE"
        }
    }

    {
        "card_id": "lcrd_128f962dbd8c4ba5e1",
        "order": {
            "id": "ord_12b4cdf5f30c158826"
            },
        "mode": "TRANSACTION",
        "payment_limit": {
            "type": "POINTS_LIMIT",
            "points_limit": {
                "max": 100
            }
        }
    }

    {
        "card_id": "lcrd_128f962dbd8c4ba5e1",
        "order": {
            "id": "ord_12b4cdf5f30c158827"
        },
        "mode": "TRANSACTION",
        "payment_limit": {
            "type": "AMOUNT_LIMIT",
            "amount_limit": {
                "max": 2000
            }
        }
    }

The response differs depending on the mode used:

200 for the DRY_RUN mode.
202 for the TRANSACTION mode. Usually, returns a PENDING transaction to be processed asynchronously.

The table below describes how individual schema properties differ between the two execution response structures.

JSON Property	`DRY_RUN` mode (simulation)	`TRANSACTION` mode (live)	Notes
`status`	`"DRY_RUN"`	`"TRANSACTION_CREATED"`	Indicates the processing method used by Voucherify.
`message`	`"Dry run mode. No transaction was created..."`	`"Pay with points transaction created"`	Returns a mode-specific descriptive system notification.
`transaction.id`	Omitted	`"lotx_12b8dbf787c67de367"`	Unique identifier generated only for live, persistent records.
`transaction.card_transaction_id`	`null`	`"lctx_12b8dbf787c67de366"`	Populates with a tracking ID during live balance changes.
`transaction.status`	`"SIMULATED"`	`"PENDING"`	Reflects workflow state tracking (mock engine vs. active processing queue).
`transaction.created_at`	Omitted	`"2026-07-13T17:22:19.296Z"`	Generated exclusively when the state transaction object is written to the database.

The transaction details regarding the point or amount limit and the actual number of points spent (or to be spent for the DRY_RUN) are returned in the details.payment object (lines 18–22).

    {
        "transaction": {
            "id": "lotx_12b8861fdd0dd35462",
            "program_id": "lprg_128f58429f4c4bf7b2",
            "member_id": "lmbr_128f962dbc8c4ba5dc",
            "card_id": "lcrd_128f962dbd8c4ba5e1",
            "card_definition_id": "lcdef_128f4a88414c4bed69",
            "card_transaction_id": "lctx_12b8861fdd0dd35461",
            "order_id": "ord_12b4cdf5f30c158825",
            "status": "PENDING",
            "type": "PAY_WITH_POINTS",
            "details": {
                "reason": "Points spent on order payment",
                "rejection": null,
                "metadata": {},
                "payment": {
                    "amount": 200,
                    "points_spent": 200,
                    "exchange_ratio": 1
                }
            },
            "created_at": "2026-07-13T11:07:16.212Z",
            "updated_at": null,
            "object": "order_transaction"
        },
        "status": "TRANSACTION_CREATED",
        "message": "Pay with points transaction created"
    }

    {
        "transaction": {
            "id": "lotx_12b884c72b0dd352b9",
            "program_id": "lprg_128f58429f4c4bf7b2",
            "member_id": "lmbr_128f962dbc8c4ba5dc",
            "card_id": "lcrd_128f962dbd8c4ba5e1",
            "card_definition_id": "lcdef_128f4a88414c4bed69",
            "card_transaction_id": "lctx_12b884c72b0dd352b8",
            "order_id": "ord_12b4cdf5f30c158826",
            "status": "PENDING",
            "type": "PAY_WITH_POINTS",
            "details": {
                "reason": "Points spent on order payment",
                "rejection": null,
                "metadata": {
                    "points_limit": 12
                },
                "payment": {
                    "amount": 12,
                    "points_spent": 12,
                    "exchange_ratio": 1
                }
            },
            "created_at": "2026-07-13T11:01:23.245Z",
            "updated_at": null,
            "object": "order_transaction"
        },
        "status": "TRANSACTION_CREATED",
        "message": "Pay with points transaction created"
    }

    {
        "transaction": {
            "id": "lotx_12b8939fd78dd3657f",
            "program_id": "lprg_128f58429f4c4bf7b2",
            "member_id": "lmbr_128f962dbc8c4ba5dc",
            "card_id": "lcrd_128f962dbd8c4ba5e1",
            "card_definition_id": "lcdef_128f4a88414c4bed69",
            "card_transaction_id": "lctx_12b8939fd78dd3657e",
            "order_id": "ord_12b4cdf5f30c158827",
            "status": "PENDING",
            "type": "PAY_WITH_POINTS",
            "details": {
                "reason": "Points spent on order payment",
                "rejection": null,
                "metadata": {
                    "amount_limit": 2000
                },
                "payment": {
                    "amount": 2000,
                    "points_spent": 2000,
                    "exchange_ratio": 1
                }
            },
            "created_at": "2026-07-13T12:06:15.135Z",
            "updated_at": null,
            "object": "order_transaction"
        },
        "status": "TRANSACTION_CREATED",
        "message": "Pay with points transaction created"
    }

If the loyalty card has no points, Voucherify returns error code 423 – “Card balance is zero”.

Pay with points response: No balance – error 423

    {
        "code": 423,
        "key": "zero_card_balance",
        "message": "Card balance is zero",
        "details": "Operation requires a positive card balance",
        "request_id": "v-12b8894b3ec1a59873"
    }

Purchase reward

Use the POST Purchase reward endpoint to create a store where your loyalty program members can buy rewards. In the request body, send the reward ID (reward_id) to be purchased. Since rewards are assigned to specific card definitions, Voucherify will subtract the required number of points from a loyalty card that’s governed by the card definition. Use the details object (response lines 11–19) to display how many points were spent on the reward purchase. If the loyalty program uses several card definitions, use the card_id (line 4) to tie the purchase to a specific loyalty card.

{
    "reward_id": "lrew_128f4cefbad47c863e"
}

{
  "transaction": {
    "id": "lrtx_1299a9ded817f57b90",
    "card_id": "lcrd_128f962dbd8c4ba5df",
    "card_transaction_id": "lctx_1299a9ded817f57b8f",
    "program_id": "lprg_128f58429f4c4bf7b2",
    "member_id": "lmbr_128f962dbc8c4ba5dc",
    "reward_id": "lrew_128f4cefbad47c863e",
    "status": "PENDING",
    "type": "PURCHASE",
    "details": {
      "reason": "Points spent on reward",
      "rejection": null,
      "metadata": {},
      "points": {
        "total": 250
      },
      "result": null
    },
    "created_at": "2026-06-19T11:50:32.033Z",
    "updated_at": null,
    "object": "reward_transaction"
  },
  "status": "TRANSACTION_CREATED",
  "message": "Reward purchase transaction created"
}

Cancellation

Your loyalty program should also support situations when a member wants to stop participating in the program, have their member profile deleted altogether, or cases when you need to temporarily suspend member activity when suspecting program fraud.

Deactivate

Use the POST Deactivate member endpoint to suspend a member’s participation in the program. A suspended member can’t earn points or spend them on rewards or orders.

Activating member againIf you need to reactivate the member, so that they can participate in the loyalty program again, use the POST Activate member endpoint.

Delete

If you need a mechanism for deleting member data, use the DELETE Member endpoint to soft-delete the member and all their associated cards within the program.

Customer data in VoucherifyThe DELETE Member endpoint deletes only the data regarding the member profile. However, the member still has a customer profile in Voucherify.Read how to delete customer data from Voucherify.

Develop

Incentivize

Explore

Integrate

Integrate loyalty v2

Preparation

Acquisition

Discovery

Examine earning rules

ALL trigger

SPECIFIC trigger: Order paid

SPECIFIC trigger: Customer entered segment

SPECIFIC trigger: Custom event

Examine rewards

AVAILABLE status

UNAVAILABLE status

Examine rewards: Example request and response

Activity

Create order

Custom events

Enter segment

Retention

Get program membership

Member

Points

Tiers

List transactions

List reward purchases

Fulfillment

Pay with points

Purchase reward

Cancellation

Deactivate

Delete

​Preparation

​Acquisition

​Discovery

​Examine earning rules

​ALL trigger

​SPECIFIC trigger: Order paid

​SPECIFIC trigger: Customer entered segment

​SPECIFIC trigger: Custom event

​Examine rewards

​AVAILABLE status

​UNAVAILABLE status

​Examine rewards: Example request and response

​Activity

​Create order

​Custom events

​Enter segment

​Retention

​Get program membership

​Member

​Points

​Tiers

​List transactions

​List reward purchases

​Fulfillment

​Pay with points

​Purchase reward

​Cancellation

​Deactivate

​Delete

Preparation

Acquisition

Discovery

Examine earning rules

ALL trigger

SPECIFIC trigger: Order paid

SPECIFIC trigger: Customer entered segment

SPECIFIC trigger: Custom event

Examine rewards

AVAILABLE status

UNAVAILABLE status

Examine rewards: Example request and response

Activity

Create order

Custom events

Enter segment

Retention

Get program membership

Member

Points

Tiers

List transactions

List reward purchases

Fulfillment

Pay with points

Purchase reward

Cancellation

Deactivate

Delete