Card definitions: Overview

Understand how card definitions configure the loyalty cards (point wallets) that store and govern a member’s points in Loyalty v2

A card definition is the configuration blueprint for a loyalty card. In the Loyalty hub dashboard, this 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 held, spent, returned, and eventually expired.

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: Makes the card definition editable again. However, you can’t change the statue to DRAFT once it has been assigned to a program.

Once a card definition is ACTIVE and 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 assignment endpoints. A program needs at least one active card definition before it can itself become ACTIVE. An active card definition can be deleted or removed from a program only when the program itself is deleted first.

Every activity performed on a card definition, like creation, updates, status transitions, and program assignments, is recorded and available through its activity history endpoint. The activities endpoint is useful for auditing configuration changes over time.

Related resources

• Loyalty v2 API: Overview for the full Loyalty v2 API map.
• Create point wallets for the point wallet concept as presented in the dashboard.
• Programs overview to see how card definitions are assigned to a program.
• Members overview to see how loyalty cards are issued to members from active card definitions.
• Integrate loyalty v2 for an end-to-end integration walkthrough.