PW – Lv2 endpoints overview pages

documentation/api-reference/loyalty-v2-benefits-overview.mdx

@@ -0,0 +1,37 @@
+---
+title: "Benefits overview"
+description: "Understand how benefits let Loyalty v2 earning rules grant points, material items, or digital incentives automatically."
+keywords: ['loyalty v2', 'benefits', 'earning rule benefits', 'material rewards', 'digital rewards']
+---
+
+A benefit is a value granted automatically to a member when an earning rule's conditions are met — as an alternative to, or alongside, earning points on a loyalty card. Members don't redeem benefits themselves; they simply receive one once they fulfill the conditions of the earning rule that references it. Benefits are optional and are only useful once connected to at least one earning rule.
+
+## Benefit types
+
+A benefit must define exactly one type-specific configuration object that matches its `type`:
+- `points` — a fixed number of points added to a card.
+- `points_proportional` — points calculated proportionally to a triggering value, such as order amount.
+- `material` — a physical product or SKU.
+- `digital` — a discount coupon or gift card.
+
+## Stock
+
+Like rewards, benefits can be limited in quantity through a `stock` configuration. When omitted, a benefit defaults to `UNLIMITED` stock, meaning it can be granted as many times as its earning rule fires.
+
+## Referenced resources
+
+Depending on its type, a benefit references other resources — a card definition for points-based benefits, or a product/SKU/campaign for material and digital benefits. These references are validated on create and update: for example, a points-based benefit can only be activated if its connected card definition is itself `ACTIVE`.
+
+## Lifecycle
+
+A benefit is created in `DRAFT` status by default, and only moves between `DRAFT` and `ACTIVE` through the activate and draft endpoints — there is no `INACTIVE` state. While in `DRAFT`, every property can be updated; once `ACTIVE`, only `name` and `stock` can still change.
+
+Two safeguards protect benefits that are already wired into your program:
+- A benefit that's referenced by any earning rule can't be deleted until that reference is removed.
+- A benefit connected to an active earning rule can't be moved back to `DRAFT`.
+
+## Related resources
+
+- [Earning Rules overview](/api-reference/loyalty-v2-earning-rules-overview) for how benefits are triggered
+- [Rewards overview](/api-reference/loyalty-v2-rewards-overview) for the point-redeemable counterpart to benefits
+- [Benefit builder](/build/create-benefit) for the dashboard perspective on configuring benefits

documentation/api-reference/loyalty-v2-card-definitions-overview.mdx

@@ -0,0 +1,41 @@
+---
+title: "Card Definitions overview"
+description: "Understand how card definitions configure the loyalty cards (point wallets) that store and govern a member's points in Loyalty v2."
+keywords: ['loyalty v2', 'card definitions', 'point wallets', 'points expiration', 'earning limits', 'spending limits']
+---
+
+A card definition is the configuration blueprint for a loyalty card. In the **Loyalty hub** dashboard, this same resource is called a **point wallet**. Every loyalty card a member holds is generated from a card definition, which controls how points on that card are earned, held, spent, and eventually expire.
+
+A loyalty program can reference multiple card definitions. When a customer becomes a member of a program, Voucherify automatically creates one loyalty card for each active card definition assigned to that program, so a member can hold several point balances at once (for example, a standard points wallet and a separate seasonal-promotion wallet).
+
+## What a card definition controls
+
+Besides `name` and `type`, a card definition groups several independent configuration sections. Any section left out on creation falls back to a permissive default:
+- `code_config` — the pattern used to generate loyalty card codes (defaults to a 10-character alphanumeric pattern).
+- `points_expiration` — whether and how points expire (defaults to `NO_EXPIRATION`).
+- `pending_points` — whether newly earned points are available immediately or held back for a period, until a fixed date, or until an activation event (defaults to `IMMEDIATE`).
+- `earning_limits` and `spending_limits` — global and per-transaction caps on how many points a member can earn or spend (default to `NO_LIMIT`).
+- `refunds` — what happens to earned or spent points when a related order is refunded (default to `NONE`).
+- `balance_settings` — whether the card balance is allowed to go negative (defaults to disallowed).
+- `pay_with_points` — the exchange ratio formula used when members pay for orders with points.
+
+## Lifecycle
+
+A card definition is created in `DRAFT` status by default. Use the activate and draft endpoints to move it between `DRAFT` and `ACTIVE`:
+- `DRAFT` → `ACTIVE`: makes the card definition eligible to be assigned to a program and used for new loyalty cards.
+- `ACTIVE` → `DRAFT`: takes the card definition out of circulation for new assignments.
+
+Once a card definition is in use — for example assigned to a program that already issued cards from it — most configuration sections become locked to protect existing point balances. Only `name`, `metadata`, and `pay_with_points` can always be updated regardless of usage; other sections may be rejected with a resource-locked error until the card definition is no longer referenced.
+
+## How card definitions fit into a program
+
+Card definitions are standalone resources, created and managed independently of any single program, then connected through the [Programs](/api-reference/loyalty-v2-programs-overview) assignment endpoints. A program needs at least one active card definition before it can itself become `ACTIVE`. Deleting a card definition or removing its assignment does not delete the loyalty cards already issued from it, but it does stop new cards from that definition being created for future members.
+
+Every activity performed on a card definition — creation, updates, status transitions, and program assignments — is recorded and available through its activity history endpoint, which is useful for auditing configuration changes over time.
+
+## Related resources
+
+- [Point wallet builder](/build/point-wallet-builder) for the point wallet concept as presented in the dashboard.
+- [Programs overview](/api-reference/loyalty-v2-programs-overview) to see how card definitions are assigned to a program.
+- [Members overview](/api-reference/loyalty-v2-members-overview) to see how loyalty cards are issued to members from active card definitions.
+- [Integrate loyalty v2](/guides/loyalty-v2-integrate) for an end-to-end integration walkthrough.

documentation/api-reference/loyalty-v2-earning-rules-overview.mdx

@@ -0,0 +1,42 @@
+---
+title: "Earning Rules overview"
+description: "Understand how earning rules define when and how Loyalty v2 members earn points or receive benefits."
+keywords: ['loyalty v2', 'earning rules', 'triggers', 'trigger limits', 'points']
+---
+
+An earning rule defines when a member earns points, or receives another configured result, for something they did. Each earning rule combines a trigger, optional conditions, and one or more earnings — Voucherify evaluates a member's earning rules and applies the first matching earning configuration for the triggering event.
+
+## Triggers
+
+An earning rule reacts to one of three triggers:
+- **Order paid** — fires after an order is successfully paid, and can calculate points proportionally to the order or item amounts.
+- **Custom event** — fires when a selected custom event is sent to Voucherify.
+- **Segment entered** — fires when a member enters a selected customer segment.
+
+## Conditions and earnings
+
+Beyond the trigger itself, a rule can require that the member belongs to a specific loyalty tier, or that the triggering event meets additional criteria (for example, a minimum order amount). Each earning inside the rule then defines its effect — typically adding points to a point wallet, but an earning can also grant a benefit instead of points. A single rule can hold multiple earnings, evaluated in order, with the first matching one applied.
+
+## Trigger limits
+
+Trigger limits control how often a rule is allowed to fire for the same member: a cooldown period between triggers, and/or a frequency cap over a time window. When omitted, a rule defaults to no cooldown and no frequency limit, meaning it can fire every time its trigger occurs.
+
+## Lifecycle
+
+An earning rule is created in `DRAFT` status unless `status` is specified explicitly. From there:
+- `DRAFT` or `INACTIVE` → `ACTIVE` via the activate endpoint.
+- `ACTIVE` → `INACTIVE` via the deactivate endpoint.
+- `ACTIVE` → `DRAFT` via the draft endpoint.
+
+Once a rule leaves `DRAFT`, only a subset of properties can still be changed — name, earnings, error handling, validity hours, start/end dates, trigger limits, and metadata — while trigger and condition definitions stay fixed. Deleting a rule performs a soft delete and keeps its last state for reference.
+
+## Assigning earning rules to a program
+
+Earning rules are created independently of any program and connected through the [Programs](/api-reference/loyalty-v2-programs-overview) batch assignment endpoint. Unlike card definitions, earning rules can be assigned or unassigned while the program is `ACTIVE`, as long as the program keeps at least one active earning rule.
+
+## Related resources
+
+- [Programs overview](/api-reference/loyalty-v2-programs-overview)
+- [Benefits overview](/api-reference/loyalty-v2-benefits-overview) for the benefit effect an earning can grant
+- [Examine overview](/api-reference/loyalty-v2-examine-overview) to simulate what an earning rule would grant before it fires
+- [Earning rule builder](/build/loyalty-earning-rule) for the dashboard perspective on earning rules

documentation/api-reference/loyalty-v2-examine-overview.mdx

@@ -0,0 +1,32 @@
+---
+title: "Examine overview"
+description: "Understand how the examine endpoints estimate earning opportunities and reward availability for a Loyalty v2 member without any side effects."
+keywords: ['loyalty v2', 'examine earning rules', 'examine rewards', 'dry run', 'points estimation']
+---
+
+The Examine endpoints let you evaluate what a member could earn or redeem across their loyalty program memberships, without creating any transactions or otherwise changing stored data. Because they are pure dry runs, you can call them as often as needed to power member-facing UI, such as "ways to earn" screens or reward catalogs.
+
+## Examine earning rules
+
+This endpoint estimates the points and benefits a member would receive for a given scenario. You choose a trigger mode:
+- `ALL` — evaluates every active earning rule across the member's programs at once, useful for showing all the available ways a member can earn points in a single call.
+- `SPECIFIC` — evaluates only the earning rules tied to one event: an order being paid, a customer entering a segment, or a custom event. This mode requires the matching context object for that event (for example, order line items for `customer.order.paid`).
+
+The response lists the estimated points per card and per earning rule, plus any material or digital benefits that would be granted. Because the estimation is a single dry-run pass, it does not chain further consequences of the earned points — for example, it won't simulate a tier upgrade that itself unlocks additional points.
+
+## Examine rewards
+
+This endpoint evaluates every reward assigned to a member's active program memberships and reports whether each one is currently redeemable on each of the member's cards. You can scope the evaluation to a single membership with `member_id`.
+
+Each reward on each card is classified as:
+- `AVAILABLE` — the member has an active card for the reward's card definition, the card balance covers the resolved point cost, and the reward assignment has stock.
+- `UNAVAILABLE` — accompanied by one or more structured reasons, such as `insufficient_balance` (with the exact points still missing), `out_of_stock`, `no_matching_cost`, `no_card_for_cost`, or `reward_inactive`.
+
+The structured unavailability reasons are designed so your frontend doesn't need to guess why a reward is greyed out — you can use the same response to render progress bars or "points needed" messaging.
+
+## Related resources
+
+- [Earning Rules overview](/api-reference/loyalty-v2-earning-rules-overview)
+- [Rewards overview](/api-reference/loyalty-v2-rewards-overview)
+- [Members overview](/api-reference/loyalty-v2-members-overview)
+- [Integrate loyalty v2](/guides/loyalty-v2-integrate) for worked examples of both examine endpoints

documentation/api-reference/loyalty-v2-members-overview.mdx

@@ -0,0 +1,43 @@
+---
+title: "Members overview"
+description: "Understand how customers are enrolled as members of a Loyalty v2 program, and how their loyalty cards, points, rewards, and payments are managed."
+keywords: ['loyalty v2', 'loyalty members', 'loyalty cards', 'pending points', 'reward purchases', 'pay with points']
+---
+
+A member is a Voucherify customer enrolled in a specific loyalty program. Membership is program-scoped: the same customer can be a member of several programs at once, but only once per program — a second enrollment attempt for the same customer is rejected. The customer must already exist in Voucherify, and the target program must be `ACTIVE` before it can accept new members.
+
+## Enrollment
+
+Members can be created one at a time, or in bulk through a batch endpoint that processes up to 10 MB of entries asynchronously in batches of 100, tracked as an [async action](/api-reference/async-actions/async-action-object). When a member is created, Voucherify automatically issues one loyalty card for every active card definition assigned to the program, so a member can start with several point wallets at once. Card `code` generation happens asynchronously, so a newly created card's `code` may briefly be `null`.
+
+## Member lifecycle
+
+A member is typically `ACTIVE` on creation, but can also be created as `INACTIVE`. Use the activate and deactivate endpoints to move a member between these two states — an inactive member can't earn or spend points. Deleting a member soft-deletes the member and its cards.
+
+## Loyalty cards and points
+
+Each of a member's loyalty cards tracks its own balance, lifetime point counters, and upcoming activation or expiration events. Beyond the automatic earning and spending flows, several endpoints let you manage points on a specific card directly:
+- Manually add or subtract points, which records an admin credit or debit transaction.
+- List, and optionally manually activate or cancel, **pending points** buckets before their scheduled activation date.
+- List, and optionally manually expire, **expiring points** buckets before their scheduled expiration date.
+- List the full transaction history of a card, or pull an aggregated daily points report for a date range.
+
+## Rewards and payments
+
+Members spend points in two ways, both scoped to a member's card:
+- **Purchasing a reward** — spends points from the card tied to the reward's cost configuration, and can later be refunded, which returns the points to the card.
+- **Paying for an order with points** — spends points based on the card definition's pay-with-points exchange ratio, capped by the card balance or an optional payment limit, and can be run as a dry run before committing to a real transaction.
+
+Members also expose read-only history for benefit fulfillments and tier transitions (joins, upgrades, downgrades, prolongations, and exits), so you can build a complete activity feed for a member without combining several other endpoints.
+
+## Member vs. membership
+
+Two related endpoints return a member's data from different angles: get member returns the member together with its cards within one program, while get membership additionally enriches each card with tier progress. Use membership whenever your integration needs to show a member's progress toward the next loyalty tier.
+
+## Related resources
+
+- [Programs overview](/api-reference/loyalty-v2-programs-overview)
+- [Card Definitions overview](/api-reference/loyalty-v2-card-definitions-overview)
+- [Rewards overview](/api-reference/loyalty-v2-rewards-overview)
+- [Tier Structures overview](/api-reference/loyalty-v2-tier-structures-overview)
+- [Integrate loyalty v2](/guides/loyalty-v2-integrate) for a step-by-step member integration walkthrough

documentation/api-reference/loyalty-v2-programs-overview.mdx

@@ -0,0 +1,38 @@
+---
+title: "Programs overview"
+description: "Understand how a Loyalty v2 program connects card definitions, earning rules, tier structures, and rewards into one customer-facing loyalty setup."
+keywords: ['loyalty v2', 'loyalty programs', 'program assignments', 'loyalty hub', 'spending reports']
+---
+
+A loyalty program is the container that ties the individual Loyalty v2 building blocks — card definitions (point wallets), earning rules, tier structures, and rewards — into a single, customer-facing loyalty setup. Members join a program, not an individual card definition or earning rule, which is what lets a program combine several of these components into one experience.
+
+## Program status
+
+A program is created in `DRAFT` status by default, and can be created directly as `ACTIVE` if it already has the required assignments. To become or remain `ACTIVE`, a program must have at least one active card definition and at least one active earning rule assigned; otherwise activation is rejected. Deleting a program soft-deletes it and removes all of its card definition, earning rule, reward, and tier structure assignments.
+
+## Assigning components to a program
+
+Card definitions, earning rules, tier structures, and rewards are all created independently (see their respective overview pages) and then connected to a program through dedicated batch assignment endpoints, one per component type. Each batch call can assign and unassign multiple items in a single request; unassign operations are always processed before assign operations, and — in the default strict mode — any missing resource or missing assignment fails the whole batch.
+
+A few rules are specific to each component:
+- **Card definitions**: can only be batch-assigned or unassigned while the program is in `DRAFT` status.
+- **Earning rules**: can be assigned or unassigned at any time, but if the program is `ACTIVE`, the batch is validated to leave at least one active earning rule assigned.
+- **Tier structures**: a program can have at most one tier structure assigned, and it can only be unassigned while the program is in `DRAFT` status.
+- **Rewards**: each reward being assigned must include its stock configuration, which can later be updated through a dedicated endpoint without going through the batch flow.
+
+## Reporting
+
+A program exposes aggregated points-spending reports — a daily breakdown over a chosen date range and resolution, and an all-time summary — optionally filtered by card definition. Use these reports to track how quickly members exhaust their point balances across the program's wallets.
+
+## Activity history
+
+Every change to a program — creation, updates, deletion, activation, deactivation, and assignment changes — is recorded and available through its activity history endpoint, giving you an audit trail independent of your own event logging.
+
+## Related resources
+
+- [Card Definitions overview](/api-reference/loyalty-v2-card-definitions-overview)
+- [Earning Rules overview](/api-reference/loyalty-v2-earning-rules-overview)
+- [Tier Structures overview](/api-reference/loyalty-v2-tier-structures-overview)
+- [Rewards overview](/api-reference/loyalty-v2-rewards-overview)
+- [Members overview](/api-reference/loyalty-v2-members-overview) for enrolling customers into a program
+- [Loyalty program overview](/build/loyalty-overview) for the dashboard perspective on programs