> ## Documentation Index > Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt > Use this file to discover all available pages before exploring further. # Draft 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 subject to change. If you want to share feedback or improvements, contact Voucherify support or your Technical Account Manager. Transitions the card definition from `ACTIVE` back to `DRAFT`. No request body. Drafting from any other state results in an invalid state transition error (409). ## OpenAPI ````yaml /openapi/loyalties-v2.json post /v2/loyalties/card-definitions/{cardDefinitionId}/draft 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: - bearerAuth: [] X-App-Id: [] X-App-Token: [] 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), 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}/draft: post: tags: - Card Definitions summary: Draft 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 subject to change. If you want to share feedback or improvements, contact Voucherify support or your Technical Account Manager. Transitions the card definition from `ACTIVE` back to `DRAFT`. No request body. Drafting from any other state results in an invalid state transition error (409). operationId: draftCardDefinition 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 drafted 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: Identifier of the request 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: bearerAuth: type: http scheme: bearer bearerFormat: JWT X-App-Id: type: apiKey name: X-App-Id in: header X-App-Token: type: apiKey name: X-App-Token in: header ````