--- title: "Get Card Definition" method: GET path: "/v2/loyalties/card-definitions/{cardDefinitionId}" tags: ["Card Definitions"] --- # Get Card Definition `GET /v2/loyalties/card-definitions/{cardDefinitionId}` Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a single card definition by its ID. ## Path parameters - `id` string, required ## Response `200` The card definition. - CardDefinition — A card definition. - `id` string, required — Unique card definition ID. - `name` string, required — Card definition name. - `type` 'INDIVIDUAL', required — Card definition type. - `status` 'DRAFT' | 'ACTIVE' | 'DELETED', required — Current card definition status. - `code_config` CardDefinitionCodeConfig, required — Card code generation configuration. Always present with server-side defaults applied. - `pattern` string, required — Code pattern where each `#` is replaced with a random character from the charset. - `length` integer, required — Number of `#` placeholders in the pattern. - `charset` string, required — Characters used for code generation. - `prefix` string, required — Fixed prefix prepended to every generated code. Empty string when not set. - `postfix` string, required — Fixed postfix appended to every generated code. Empty string when not set. - `points_expiration` CardDefinitionPointsExpiration, required — Points expiration policy. Always present; defaults to `NO_EXPIRATION`. - `type` 'NO_EXPIRATION' | 'ROLLING_EXPIRATION' | 'CALENDAR_EXPIRATION' | 'SLIDING_EXPIRATION', required — Points expiration type. - `rolling_expiration` CardDefinitionPointsExpirationRollingExpiration — Rolling expiration configuration. - `period` CardDefinitionPeriod, required — A period expressed as a value and unit. - `value` integer, required — Period length. - `unit` 'DAY' | 'MONTH' | 'YEAR', required — Period unit. - `rounding` CardDefinitionPointsExpirationRollingExpirationRounding — Rounding of the rolling expiration date. - `type` 'END_OF_MONTH' | 'END_OF_QUARTER' | 'END_OF_HALF_YEAR' | 'END_OF_YEAR' | 'END_OF_PARTICULAR_MONTH', required — Rounding type. - `value` integer — Month number (1-12). Only present when `type` is `END_OF_PARTICULAR_MONTH`. - `calendar_expiration` CardDefinitionPointsExpirationCalendarExpiration — Calendar expiration configuration. - `expiration_dates` CardDefinitionCalendarDate[], required — Calendar dates on which points expire. - `day` integer, required — Day of the month. - `month` integer, required — Month number (1-12). - `sliding_expiration` CardDefinitionPointsExpirationSlidingExpiration — Sliding expiration configuration. - `earning_activity` boolean — Whether earning points resets the expiration window. - `spending_activity` boolean — Whether spending points resets the expiration window. - `custom_activity` boolean — Whether the configured custom events reset the expiration window. - `custom_activity_types` string[], required — Custom event schema IDs that reset the expiration window. Empty array when `custom_activity` is false. - `period` CardDefinitionPeriod, required — A period expressed as a value and unit. - `value` integer, required — Period length. - `unit` 'DAY' | 'MONTH' | 'YEAR', required — Period unit. - `pending_points` CardDefinitionPendingPoints, required — Pending points activation policy. Always present; defaults to `IMMEDIATE`. - `type` 'IMMEDIATE' | 'PERIOD_BASED' | 'FIXED_DATES' | 'EVENT_BASED', required — Pending points activation type. - `period_based` CardDefinitionPendingPointsPeriodBased — Period-based pending points activation. - `period` CardDefinitionPeriod, required — A period expressed as a value and unit. - `value` integer, required — Period length. - `unit` 'DAY' | 'MONTH' | 'YEAR', required — Period unit. - `fixed_dates` CardDefinitionPendingPointsFixedDates — Fixed-dates pending points activation. - `dates` CardDefinitionCalendarDate[], required — Calendar dates on which pending points activate. - `day` integer, required — Day of the month. - `month` integer, required — Month number (1-12). - `event_based` CardDefinitionPendingPointsEventBased — Event-based pending points activation. - `event_types` string[], required — Custom event schema IDs that activate pending points. - `cancel_period` CardDefinitionPeriod, required — A period expressed as a value and unit. - `value` integer, required — Period length. - `unit` 'DAY' | 'MONTH' | 'YEAR', required — Period unit. - `earning_limits` CardDefinitionEarningLimits, required — Points earning limits. Always present; defaults to `NO_LIMIT` for both scopes. - `global` CardDefinitionEarningLimitsGlobal — Global (per card) earning limits. - `type` 'NO_LIMIT' | 'LIMITED', required — Whether global earning limits apply. - `limits` CardDefinitionEarningLimitsGlobalLimit[], required — Limit definitions. Empty array when `type` is `NO_LIMIT`. - union — A global earning limit: `BALANCE_BASED` or `TIME_BASED`. - object — Balance-based limit. - `type` 'BALANCE_BASED', required — Limit type. - `max` integer, required — Maximum card balance in points. - object — Time-based limit. - `type` 'TIME_BASED', required — Limit type. - `period` CardDefinitionLimitTimeBasedPeriod — Time-based limit period. - … - `points` CardDefinitionLimitTimeBasedPoints — Points cap for a time-based limit. - … - `transactions` CardDefinitionEarningLimitsTransactions — Per-transaction earning limits. - `type` 'NO_LIMIT' | 'LIMITED', required — Whether per-transaction earning limits apply. - `limits` CardDefinitionEarningLimitsTransactionsLimit[], required — Limit definitions. Empty array when `type` is `NO_LIMIT`. - union — A per-transaction earning limit: `POINTS` or `SPENDING`. - object — Points limit. - `type` 'POINTS', required — Limit type. - `max` integer, required — Maximum points earned per transaction. - object — Spending threshold. - `type` 'SPENDING', required — Limit type. - `min_amount` integer, required — Minimum transaction amount required to earn points. - `spending_limits` CardDefinitionSpendingLimits, required — Points spending limits. Always present; defaults to `NO_LIMIT` for both scopes. - `global` CardDefinitionSpendingLimitsGlobal — Global (per card) spending limits. - `type` 'NO_LIMIT' | 'LIMITED', required — Whether global spending limits apply. - `limits` CardDefinitionSpendingLimitsGlobalLimit[], required — Limit definitions. Empty array when `type` is `NO_LIMIT`. - union — A global spending limit: `SPENDING_BASED` or `TIME_BASED`. - object — Spending-based limit. - `type` 'SPENDING_BASED', required — Limit type. - `max` integer, required — Maximum total points spent. - object — Time-based limit. - `type` 'TIME_BASED', required — Limit type. - `period` CardDefinitionLimitTimeBasedPeriod — Time-based limit period. - … - `points` CardDefinitionLimitTimeBasedPoints — Points cap for a time-based limit. - … - `transactions` CardDefinitionSpendingLimitsTransactions — Per-transaction spending limits. - `type` 'NO_LIMIT' | 'LIMITED', required — Whether per-transaction spending limits apply. - `limits` CardDefinitionSpendingLimitsTransactionsLimit[], required — Limit definitions. Empty array when `type` is `NO_LIMIT`. - `type` 'POINTS', required — Limit type. - `max` integer, required — Maximum points spent per transaction. - `refunds` CardDefinitionRefunds, required — Refund handling configuration. Always present; defaults to `NONE` for both scopes. - `spent_points` CardDefinitionRefundsSpentPoints, required — How points spent on a refunded order are handled. - `type` 'NONE' | 'REFUNDABLE', required — Whether spent points are refundable. - `methods` CardDefinitionRefundsSpentPointsMethod[], required — Refund methods. Empty array when `type` is `NONE`. - `type` 'RETURN_POINTS', required — Refund method type. - `mode` 'REFUND_ALL' | 'REFUND_ITEM' | 'REFUND_AMOUNT', required — Refund mode. - `earned_points` CardDefinitionRefundsEarnedPoints, required — How points earned on a refunded order are handled. - `type` 'NONE' | 'REFUNDABLE', required — Whether earned points are revocable on refund. - `methods` CardDefinitionRefundsEarnedPointsMethod[], required — Revoke methods. Empty array when `type` is `NONE`. - union — An earned points revoke method: `REVOKE_FROM_PENDING` or `REVOKE_FROM_BALANCE`. - object — Revoke earned points from pending points. - `type` 'REVOKE_FROM_PENDING', required — Revoke method type. - object — Revoke earned points from the card balance. - `type` 'REVOKE_FROM_BALANCE', required — Revoke method type. - `mode` 'REVOKE_TO_ZERO' | 'REVOKE_BELOW_ZERO', required — Revoke mode. - `balance_settings` CardDefinitionBalanceSettings, required — Card balance settings. Always present; defaults to `allow_negative: false`. - `allow_negative` boolean, required — Whether the card balance is allowed to go below zero. - `pay_with_points` CardDefinitionPayWithPoints, required — Pay-with-points configuration. Always present; defaults to `NO_PAYMENTS`. - `type` 'NO_PAYMENTS' | 'EXCHANGE_RATIO', required — Pay-with-points type. - `exchange_ratio` object — Exchange ratio. Only present when `type` is `EXCHANGE_RATIO`. - `formula` string, required — Exchange ratio formula (always returned as a string). - `metadata` object, required — Arbitrary key-value metadata. Empty object when not set. - `created_at` string, date-time, required — Creation timestamp (ISO 8601). - `updated_at` string, date-time, nullable, required — Last update timestamp (ISO 8601). `null` when the card definition has never been updated. - `object` 'card_definition', required — Object type marker. Always `card_definition`. ## Other responses - `400` — Validation error - the request body or query parameters are invalid. - `404` — Resource not found - `409` — Conflict - invalid state transition - `500` — Internal server error --- [API](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-loyalty-v2-api/revisions/69be73b5cff0/schema)