> ## Documentation Index
> Fetch the complete documentation index at: https://voucherify-rc-lv2-guides.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Card Definition
>
BETA endpoint
This is a work-in-progress documentation of a BETA endpoint. The parameters, fields, request and response bodies, and other data may be subject to change. If you want to share feedback or improvements, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager.
Returns a single card definition by its ID.
## OpenAPI
````yaml /openapi/loyalties-v2.json get /v2/loyalties/card-definitions/{cardDefinitionId}
openapi: 3.1.0
info:
title: Voucherify Loyalty v2 API
version: 2.0.0
description: >-
Complete OpenAPI specification for the Voucherify Loyalty v2 API.
All endpoints require the LOYALTY_V2 feature flag.
Combined from per-domain specs: programs.yaml, members.yaml,
program-operations.yaml, card-definitions.yaml, earning-rules.yaml,
tier-structures.yaml, benefits.yaml, rewards.yaml, examine.yaml
servers:
- url: '{protocol}://{host}'
variables:
protocol:
default: https
enum:
- https
- http
host:
default: api.voucherify.io
security:
- X-App-Id: []
X-App-Token: []
- bearerAuth: []
tags:
- name: Programs
description: >-
Loyalty program CRUD, lifecycle management, program-scoped resource
assignments (card definitions, earning rules, rewards, tier structures),
member management (create, list, get, activate, deactivate, delete),
membership retrieval (member + program + cards with tier progress, by
customer ID, customer source ID, or member ID), card operations (points
adjustment, pending points, expiring points, transactions), reward
purchases, and activity history.
- name: Card Definitions
description: >-
CRUD operations, lifecycle management, and activity history for card
definitions. Card definitions describe the configuration for loyalty
cards, including code generation, points expiration, earning/spending
limits, pending points, refunds, and balance settings.
- name: Earning Rules
description: >-
Manage earning rules that define how customers earn points or receive
incentives based on triggers (events, segments, custom events). Includes
CRUD, lifecycle, and activity history.
- name: Tier Structures
description: >-
CRUD operations, lifecycle management, and activity history for tier
structures. Includes nested tier definitions (create, list, update,
delete) within tier structures. Tier structures define the tiering model
for loyalty programs — how members qualify for and move between tiers.
- name: Benefits
description: >-
Manage benefit definitions (fixed points, proportional points, material,
digital). Includes CRUD, lifecycle transitions, and activity history.
- name: Rewards
description: >-
CRUD, lifecycle operations, and activity history for reward definitions.
Rewards can be material (product/SKU) or digital (discount coupons, gift
vouchers).
- name: Examine
description: >-
Evaluation endpoints that estimate earning opportunities and reward
availability for a customer across their loyalty program memberships,
without side effects.
paths:
/v2/loyalties/card-definitions/{cardDefinitionId}:
get:
tags:
- Card Definitions
summary: Get Card Definition
description: >-
BETA endpoint
This is a work-in-progress documentation of a BETA endpoint. The
parameters, fields, request and response bodies, and other data may be
subject to change. If you want to share feedback or improvements,
contact [Voucherify support](https://www.voucherify.io/contact-support)
or your Technical Account Manager.
Returns a single card definition by its ID.
operationId: getCardDefinition
parameters:
- name: id
in: path
required: true
description: 'Unique card definition ID. Pattern: `^lcdef_[a-f0-9]+$`.'
schema:
type: string
pattern: ^lcdef_[a-f0-9]+$
responses:
'200':
description: The card definition.
content:
application/json:
schema:
$ref: '#/components/schemas/CardDefinition'
'400':
description: Validation error - the request body or query parameters are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Conflict - invalid state transition
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
CardDefinition:
type: object
description: A card definition.
properties:
id:
type: string
pattern: ^lcdef_[a-f0-9]+$
description: Unique card definition ID.
name:
type: string
description: Card definition name.
type:
type: string
enum:
- INDIVIDUAL
description: Card definition type.
status:
type: string
enum:
- DRAFT
- ACTIVE
- DELETED
description: Current card definition status.
code_config:
$ref: '#/components/schemas/CardDefinitionCodeConfig'
points_expiration:
$ref: '#/components/schemas/CardDefinitionPointsExpiration'
pending_points:
$ref: '#/components/schemas/CardDefinitionPendingPoints'
earning_limits:
$ref: '#/components/schemas/CardDefinitionEarningLimits'
spending_limits:
$ref: '#/components/schemas/CardDefinitionSpendingLimits'
refunds:
$ref: '#/components/schemas/CardDefinitionRefunds'
balance_settings:
$ref: '#/components/schemas/CardDefinitionBalanceSettings'
pay_with_points:
$ref: '#/components/schemas/CardDefinitionPayWithPoints'
metadata:
type: object
description: Arbitrary key-value metadata. Empty object when not set.
created_at:
type: string
format: date-time
description: Creation timestamp (ISO 8601).
updated_at:
type:
- string
- 'null'
format: date-time
description: >-
Last update timestamp (ISO 8601). Null when the card definition has
never been updated.
object:
type: string
const: card_definition
description: Object type marker. Always `card_definition`.
required:
- id
- name
- type
- status
- code_config
- points_expiration
- pending_points
- earning_limits
- spending_limits
- refunds
- balance_settings
- pay_with_points
- metadata
- created_at
- updated_at
- object
ErrorResponse:
type: object
description: Standard error response returned by all Loyalty v2 endpoints.
properties:
code:
type: integer
description: HTTP status code of the error.
key:
type: string
description: Machine-readable error key.
message:
type: string
description: Human-readable error message.
details:
type: string
description: Additional details about the error.
request_id:
type: string
description: Unique identifier of the request that produced the error.
resource_id:
type: string
description: Unique identifier of the resource that produced the error.
resource_type:
type: string
description: Type of the resource that produced the error.
CardDefinitionCodeConfig:
type: object
description: >-
Card code generation configuration. Always present with server-side
defaults applied.
properties:
pattern:
type: string
description: >-
Code pattern where each `#` is replaced with a random character from
the charset.
length:
type: integer
description: Number of `#` placeholders in the pattern.
charset:
type: string
description: Characters used for code generation.
prefix:
type: string
description: >-
Fixed prefix prepended to every generated code. Empty string when
not set.
postfix:
type: string
description: >-
Fixed postfix appended to every generated code. Empty string when
not set.
required:
- pattern
- length
- charset
- prefix
- postfix
CardDefinitionPointsExpiration:
type: object
description: Points expiration policy. Always present; defaults to `NO_EXPIRATION`.
properties:
type:
type: string
enum:
- NO_EXPIRATION
- ROLLING_EXPIRATION
- CALENDAR_EXPIRATION
- SLIDING_EXPIRATION
description: Points expiration type.
rolling_expiration:
$ref: '#/components/schemas/CardDefinitionPointsExpirationRollingExpiration'
description: >-
Rolling expiration configuration. Only present when `type` is
`ROLLING_EXPIRATION`.
calendar_expiration:
$ref: >-
#/components/schemas/CardDefinitionPointsExpirationCalendarExpiration
description: >-
Calendar expiration configuration. Only present when `type` is
`CALENDAR_EXPIRATION`.
sliding_expiration:
$ref: '#/components/schemas/CardDefinitionPointsExpirationSlidingExpiration'
description: >-
Sliding expiration configuration. Only present when `type` is
`SLIDING_EXPIRATION`.
required:
- type
CardDefinitionPendingPoints:
type: object
description: >-
Pending points activation policy. Always present; defaults to
`IMMEDIATE`.
properties:
type:
type: string
enum:
- IMMEDIATE
- PERIOD_BASED
- FIXED_DATES
- EVENT_BASED
description: Pending points activation type.
period_based:
$ref: '#/components/schemas/CardDefinitionPendingPointsPeriodBased'
description: Period-based activation. Only present when `type` is `PERIOD_BASED`.
fixed_dates:
$ref: '#/components/schemas/CardDefinitionPendingPointsFixedDates'
description: Fixed-dates activation. Only present when `type` is `FIXED_DATES`.
event_based:
$ref: '#/components/schemas/CardDefinitionPendingPointsEventBased'
description: Event-based activation. Only present when `type` is `EVENT_BASED`.
required:
- type
CardDefinitionEarningLimits:
type: object
description: >-
Points earning limits. Always present; defaults to `NO_LIMIT` for both
scopes.
properties:
global:
$ref: '#/components/schemas/CardDefinitionEarningLimitsGlobal'
transactions:
$ref: '#/components/schemas/CardDefinitionEarningLimitsTransactions'
CardDefinitionSpendingLimits:
type: object
description: >-
Points spending limits. Always present; defaults to `NO_LIMIT` for both
scopes.
properties:
global:
$ref: '#/components/schemas/CardDefinitionSpendingLimitsGlobal'
transactions:
$ref: '#/components/schemas/CardDefinitionSpendingLimitsTransactions'
CardDefinitionRefunds:
type: object
description: >-
Refund handling configuration. Always present; defaults to `NONE` for
both scopes.
properties:
spent_points:
$ref: '#/components/schemas/CardDefinitionRefundsSpentPoints'
earned_points:
$ref: '#/components/schemas/CardDefinitionRefundsEarnedPoints'
required:
- spent_points
- earned_points
CardDefinitionBalanceSettings:
type: object
description: >-
Card balance settings. Always present; defaults to `allow_negative:
false`.
properties:
allow_negative:
type: boolean
description: Whether the card balance is allowed to go below zero.
required:
- allow_negative
CardDefinitionPayWithPoints:
type: object
description: >-
Pay-with-points configuration. Always present; defaults to
`NO_PAYMENTS`.
properties:
type:
type: string
enum:
- NO_PAYMENTS
- EXCHANGE_RATIO
description: Pay-with-points type.
exchange_ratio:
type: object
description: Exchange ratio. Only present when `type` is `EXCHANGE_RATIO`.
properties:
formula:
type: string
description: Exchange ratio formula (always returned as a string).
required:
- formula
required:
- type
CardDefinitionPointsExpirationRollingExpiration:
type: object
description: Rolling expiration configuration.
properties:
period:
$ref: '#/components/schemas/CardDefinitionPeriod'
description: Rolling expiration period. Unit is one of `DAY`, `MONTH`, `YEAR`.
rounding:
oneOf:
- $ref: >-
#/components/schemas/CardDefinitionPointsExpirationRollingExpirationRounding
- type: 'null'
description: >-
Rounding applied to the calculated expiration date. Null when not
configured.
required:
- period
CardDefinitionPointsExpirationCalendarExpiration:
type: object
description: Calendar expiration configuration.
properties:
expiration_dates:
type: array
items:
$ref: '#/components/schemas/CardDefinitionCalendarDate'
description: Calendar dates on which points expire.
required:
- expiration_dates
CardDefinitionPointsExpirationSlidingExpiration:
type: object
description: Sliding expiration configuration.
properties:
earning_activity:
type: boolean
description: Whether earning points resets the expiration window.
spending_activity:
type: boolean
description: Whether spending points resets the expiration window.
custom_activity:
type: boolean
description: Whether the configured custom events reset the expiration window.
custom_activity_types:
type: array
items:
type: string
description: >-
Custom event schema IDs that reset the expiration window. Empty
array when `custom_activity` is false.
period:
$ref: '#/components/schemas/CardDefinitionPeriod'
description: Sliding expiration period. Unit is one of `DAY`, `MONTH`, `YEAR`.
required:
- custom_activity_types
- period
CardDefinitionPendingPointsPeriodBased:
type: object
description: Period-based pending points activation.
properties:
period:
$ref: '#/components/schemas/CardDefinitionPeriod'
description: Pending period. Unit is one of `DAY`, `MONTH`, `YEAR`.
required:
- period
CardDefinitionPendingPointsFixedDates:
type: object
description: Fixed-dates pending points activation.
properties:
dates:
type: array
items:
$ref: '#/components/schemas/CardDefinitionCalendarDate'
description: Calendar dates on which pending points activate.
required:
- dates
CardDefinitionPendingPointsEventBased:
type: object
description: Event-based pending points activation.
properties:
event_types:
type: array
items:
type: string
description: Custom event schema IDs that activate pending points.
cancel_period:
$ref: '#/components/schemas/CardDefinitionPeriod'
description: >-
Period after which non-activated pending points are cancelled. Unit
is one of `DAY`, `MONTH`, `YEAR`.
required:
- event_types
- cancel_period
CardDefinitionEarningLimitsGlobal:
type: object
description: Global (per card) earning limits.
properties:
type:
type: string
enum:
- NO_LIMIT
- LIMITED
description: Whether global earning limits apply.
limits:
type: array
items:
$ref: '#/components/schemas/CardDefinitionEarningLimitsGlobalLimit'
description: Limit definitions. Empty array when `type` is `NO_LIMIT`.
required:
- type
- limits
CardDefinitionEarningLimitsTransactions:
type: object
description: Per-transaction earning limits.
properties:
type:
type: string
enum:
- NO_LIMIT
- LIMITED
description: Whether per-transaction earning limits apply.
limits:
type: array
items:
$ref: '#/components/schemas/CardDefinitionEarningLimitsTransactionsLimit'
description: Limit definitions. Empty array when `type` is `NO_LIMIT`.
required:
- type
- limits
CardDefinitionSpendingLimitsGlobal:
type: object
description: Global (per card) spending limits.
properties:
type:
type: string
enum:
- NO_LIMIT
- LIMITED
description: Whether global spending limits apply.
limits:
type: array
items:
$ref: '#/components/schemas/CardDefinitionSpendingLimitsGlobalLimit'
description: Limit definitions. Empty array when `type` is `NO_LIMIT`.
required:
- type
- limits
CardDefinitionSpendingLimitsTransactions:
type: object
description: Per-transaction spending limits.
properties:
type:
type: string
enum:
- NO_LIMIT
- LIMITED
description: Whether per-transaction spending limits apply.
limits:
type: array
items:
$ref: '#/components/schemas/CardDefinitionSpendingLimitsTransactionsLimit'
description: Limit definitions. Empty array when `type` is `NO_LIMIT`.
required:
- type
- limits
CardDefinitionRefundsSpentPoints:
type: object
description: How points spent on a refunded order are handled.
properties:
type:
type: string
enum:
- NONE
- REFUNDABLE
description: Whether spent points are refundable.
methods:
type: array
items:
$ref: '#/components/schemas/CardDefinitionRefundsSpentPointsMethod'
description: Refund methods. Empty array when `type` is `NONE`.
required:
- type
- methods
CardDefinitionRefundsEarnedPoints:
type: object
description: How points earned on a refunded order are handled.
properties:
type:
type: string
enum:
- NONE
- REFUNDABLE
description: Whether earned points are revocable on refund.
methods:
type: array
items:
$ref: '#/components/schemas/CardDefinitionRefundsEarnedPointsMethod'
description: Revoke methods. Empty array when `type` is `NONE`.
required:
- type
- methods
CardDefinitionPeriod:
type: object
description: A period expressed as a value and unit.
properties:
value:
type: integer
description: Period length.
unit:
type: string
enum:
- DAY
- MONTH
- YEAR
description: Period unit.
required:
- value
- unit
CardDefinitionPointsExpirationRollingExpirationRounding:
type: object
description: Rounding of the rolling expiration date.
properties:
type:
type: string
enum:
- END_OF_MONTH
- END_OF_QUARTER
- END_OF_HALF_YEAR
- END_OF_YEAR
- END_OF_PARTICULAR_MONTH
description: Rounding type.
value:
type: integer
minimum: 1
maximum: 12
description: >-
Month number (1-12). Only present when `type` is
`END_OF_PARTICULAR_MONTH`.
required:
- type
CardDefinitionCalendarDate:
type: object
description: A calendar date (day + month).
properties:
day:
type: integer
minimum: 1
maximum: 31
description: Day of the month.
month:
type: integer
minimum: 1
maximum: 12
description: Month number (1-12).
required:
- day
- month
CardDefinitionEarningLimitsGlobalLimit:
description: 'A global earning limit: `BALANCE_BASED` or `TIME_BASED`.'
oneOf:
- type: object
description: Balance-based limit.
properties:
type:
type: string
const: BALANCE_BASED
description: Limit type.
max:
type: integer
description: Maximum card balance in points.
required:
- type
- max
- type: object
description: Time-based limit.
properties:
type:
type: string
const: TIME_BASED
description: Limit type.
period:
$ref: '#/components/schemas/CardDefinitionLimitTimeBasedPeriod'
points:
$ref: '#/components/schemas/CardDefinitionLimitTimeBasedPoints'
required:
- type
discriminator:
propertyName: type
CardDefinitionEarningLimitsTransactionsLimit:
description: 'A per-transaction earning limit: `POINTS` or `SPENDING`.'
oneOf:
- type: object
description: Points limit.
properties:
type:
type: string
const: POINTS
description: Limit type.
max:
type: integer
description: Maximum points earned per transaction.
required:
- type
- max
- type: object
description: Spending threshold.
properties:
type:
type: string
const: SPENDING
description: Limit type.
min_amount:
type: integer
description: Minimum transaction amount required to earn points.
required:
- type
- min_amount
discriminator:
propertyName: type
CardDefinitionSpendingLimitsGlobalLimit:
description: 'A global spending limit: `SPENDING_BASED` or `TIME_BASED`.'
oneOf:
- type: object
description: Spending-based limit.
properties:
type:
type: string
const: SPENDING_BASED
description: Limit type.
max:
type: integer
description: Maximum total points spent.
required:
- type
- max
- type: object
description: Time-based limit.
properties:
type:
type: string
const: TIME_BASED
description: Limit type.
period:
$ref: '#/components/schemas/CardDefinitionLimitTimeBasedPeriod'
points:
$ref: '#/components/schemas/CardDefinitionLimitTimeBasedPoints'
required:
- type
discriminator:
propertyName: type
CardDefinitionSpendingLimitsTransactionsLimit:
type: object
description: >-
A per-transaction spending limit. Currently only the `POINTS` type
exists.
properties:
type:
type: string
const: POINTS
description: Limit type.
max:
type: integer
description: Maximum points spent per transaction.
required:
- type
- max
CardDefinitionRefundsSpentPointsMethod:
type: object
description: A spent points refund method.
properties:
type:
type: string
const: RETURN_POINTS
description: Refund method type.
mode:
type: string
enum:
- REFUND_ALL
- REFUND_ITEM
- REFUND_AMOUNT
description: Refund mode.
required:
- type
- mode
CardDefinitionRefundsEarnedPointsMethod:
description: >-
An earned points revoke method: `REVOKE_FROM_PENDING` or
`REVOKE_FROM_BALANCE`.
oneOf:
- type: object
description: Revoke earned points from pending points.
properties:
type:
type: string
const: REVOKE_FROM_PENDING
description: Revoke method type.
required:
- type
- type: object
description: Revoke earned points from the card balance.
properties:
type:
type: string
const: REVOKE_FROM_BALANCE
description: Revoke method type.
mode:
type: string
enum:
- REVOKE_TO_ZERO
- REVOKE_BELOW_ZERO
description: Revoke mode.
required:
- type
- mode
discriminator:
propertyName: type
CardDefinitionLimitTimeBasedPeriod:
type: object
description: Time-based limit period.
properties:
type:
type: string
enum:
- CURRENT_PERIOD
description: Period type.
current_period:
type: object
description: >-
Current-period configuration. Present when `type` is
`CURRENT_PERIOD`.
properties:
unit:
type: string
enum:
- DAY
- WEEK
- MONTH
- QUARTER
- YEAR
description: Calendar period unit.
required:
- unit
required:
- type
CardDefinitionLimitTimeBasedPoints:
type: object
description: Points cap for a time-based limit.
properties:
max:
type: integer
description: Maximum points within the period.
required:
- max
securitySchemes:
X-App-Id:
type: apiKey
name: X-App-Id
in: header
X-App-Token:
type: apiKey
name: X-App-Token
in: header
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````