> ## 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. # Create 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. Creates a new card definition. Only `name` and `type` are required; all other sections default server-side as follows: - `code_config`: 10-character alphanumeric code pattern (`##########`) - `points_expiration`: `NO_EXPIRATION` - `pending_points`: `IMMEDIATE` - `earning_limits`: global `NO_LIMIT`, transactions `NO_LIMIT` - `spending_limits`: global `NO_LIMIT`, transactions `NO_LIMIT` - `refunds`: spent points `NONE`, earned points `NONE` - `balance_settings`: `allow_negative: false` - `pay_with_points`: `NO_PAYMENTS` Cross-field rules: - `balance_settings.allow_negative` can only be `true` when `points_expiration.type` is `NO_EXPIRATION`. Additionally, the earned points refund mode `REVOKE_BELOW_ZERO` requires `balance_settings.allow_negative` to be `true`. - The earned points refund method `REVOKE_FROM_PENDING` requires `pending_points.type` to be one of `PERIOD_BASED`, `FIXED_DATES`, `EVENT_BASED`. ## OpenAPI ````yaml /openapi/loyalties-v2.json post /v2/loyalties/card-definitions 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: post: tags: - Card Definitions summary: Create 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. Creates a new card definition. Only `name` and `type` are required; all other sections default server-side as follows: - `code_config`: 10-character alphanumeric code pattern (`##########`) - `points_expiration`: `NO_EXPIRATION` - `pending_points`: `IMMEDIATE` - `earning_limits`: global `NO_LIMIT`, transactions `NO_LIMIT` - `spending_limits`: global `NO_LIMIT`, transactions `NO_LIMIT` - `refunds`: spent points `NONE`, earned points `NONE` - `balance_settings`: `allow_negative: false` - `pay_with_points`: `NO_PAYMENTS` Cross-field rules: - `balance_settings.allow_negative` can only be `true` when `points_expiration.type` is `NO_EXPIRATION`. Additionally, the earned points refund mode `REVOKE_BELOW_ZERO` requires `balance_settings.allow_negative` to be `true`. - The earned points refund method `REVOKE_FROM_PENDING` requires `pending_points.type` to be one of `PERIOD_BASED`, `FIXED_DATES`, `EVENT_BASED`. operationId: createCardDefinition requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CardDefinitionCreateRequest' responses: '200': description: The created 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: CardDefinitionCreateRequest: type: object description: >- Request body for creating a card definition. Cross-field rules apply: `balance_settings.allow_negative: true` requires `points_expiration.type` to be `NO_EXPIRATION`; the earned points refund mode `REVOKE_BELOW_ZERO` requires `allow_negative: true`; and the earned points refund method `REVOKE_FROM_PENDING` requires `pending_points.type` to be `PERIOD_BASED`, `FIXED_DATES` or `EVENT_BASED`. properties: name: type: string minLength: 1 maxLength: 200 description: Card definition name. type: type: string enum: - INDIVIDUAL description: Card definition type. Currently only `INDIVIDUAL` is supported. status: type: - string - 'null' enum: - DRAFT - ACTIVE - null description: >- Initial status. Allowed values on create are `DRAFT` and `ACTIVE`. Defaults to `DRAFT` when omitted. code_config: oneOf: - $ref: '#/components/schemas/CardDefinitionCodeConfigInput' - type: 'null' description: >- Card code generation configuration. Defaults to a 10-character alphanumeric pattern. points_expiration: oneOf: - $ref: '#/components/schemas/CardDefinitionPointsExpirationInput' - type: 'null' description: Points expiration policy. Defaults to `NO_EXPIRATION`. pending_points: oneOf: - $ref: '#/components/schemas/CardDefinitionPendingPointsInput' - type: 'null' description: Pending points activation policy. Defaults to `IMMEDIATE`. earning_limits: oneOf: - $ref: '#/components/schemas/CardDefinitionEarningLimitsInput' - type: 'null' description: >- Points earning limits. Defaults to `NO_LIMIT` for both global and transaction limits. spending_limits: oneOf: - $ref: '#/components/schemas/CardDefinitionSpendingLimitsInput' - type: 'null' description: >- Points spending limits. Defaults to `NO_LIMIT` for both global and transaction limits. refunds: oneOf: - $ref: '#/components/schemas/CardDefinitionRefundsInput' - type: 'null' description: >- Refund handling configuration. Defaults to `NONE` for both spent and earned points. balance_settings: oneOf: - $ref: '#/components/schemas/CardDefinitionBalanceSettingsInput' - type: 'null' description: 'Card balance settings. Defaults to `allow_negative: false`.' pay_with_points: oneOf: - $ref: '#/components/schemas/CardDefinitionPayWithPointsInput' - type: 'null' description: Pay-with-points configuration. Defaults to `NO_PAYMENTS`. metadata: type: - object - 'null' description: Arbitrary key-value metadata attached to the card definition. required: - name - type additionalProperties: false 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. CardDefinitionCodeConfigInput: type: object description: >- Card code generation configuration. When `pattern` is provided, the effective code length is the number of `#` placeholders in the pattern; otherwise `length` (default 10) `#` placeholders are used. properties: length: type: - integer - 'null' description: >- Number of generated characters in the code (ignored when `pattern` is provided). A positive integer. Defaults to 10. charset: type: - string - 'null' description: >- Characters used for code generation. Defaults to alphanumeric: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ`. prefix: type: - string - 'null' description: >- Fixed prefix prepended to every generated code. Defaults to an empty string. postfix: type: - string - 'null' description: >- Fixed postfix appended to every generated code. Defaults to an empty string. pattern: type: - string - 'null' description: >- Code pattern where each `#` is replaced with a random character from the charset, e.g. `###-###`. Defaults to `#` repeated `length` times. additionalProperties: false CardDefinitionPointsExpirationInput: type: object description: >- Points expiration policy. Conditional requirements based on `type`: - `NO_EXPIRATION`: `rolling_expiration`, `calendar_expiration` and `sliding_expiration` must be null/absent. - `ROLLING_EXPIRATION`: `rolling_expiration` is required; the other two must be null/absent. - `CALENDAR_EXPIRATION`: `calendar_expiration` is required; the other two must be null/absent. - `SLIDING_EXPIRATION`: `sliding_expiration` is required; the other two must be null/absent. properties: type: type: string enum: - NO_EXPIRATION - ROLLING_EXPIRATION - CALENDAR_EXPIRATION - SLIDING_EXPIRATION description: Points expiration type. rolling_expiration: oneOf: - $ref: >- #/components/schemas/CardDefinitionPointsExpirationRollingExpirationInput - type: 'null' description: >- Rolling expiration configuration. Required when `type` is `ROLLING_EXPIRATION`, must be null otherwise. calendar_expiration: oneOf: - $ref: >- #/components/schemas/CardDefinitionPointsExpirationCalendarExpirationInput - type: 'null' description: >- Calendar expiration configuration. Required when `type` is `CALENDAR_EXPIRATION`, must be null otherwise. sliding_expiration: oneOf: - $ref: >- #/components/schemas/CardDefinitionPointsExpirationSlidingExpirationInput - type: 'null' description: >- Sliding expiration configuration. Required when `type` is `SLIDING_EXPIRATION`, must be null otherwise. required: - type additionalProperties: false CardDefinitionPendingPointsInput: type: object description: >- Pending points activation policy. Conditional requirements based on `type`: - `IMMEDIATE`: `period_based`, `fixed_dates` and `event_based` must be null/absent. - `PERIOD_BASED`: `period_based` is required; the other two must be null/absent. - `FIXED_DATES`: `fixed_dates` is required; the other two must be null/absent. - `EVENT_BASED`: `event_based` is required; the other two must be null/absent. properties: type: type: string enum: - IMMEDIATE - PERIOD_BASED - FIXED_DATES - EVENT_BASED description: Pending points activation type. `IMMEDIATE` means no pending period. period_based: oneOf: - $ref: '#/components/schemas/CardDefinitionPendingPointsPeriodBasedInput' - type: 'null' description: >- Period-based activation. Required when `type` is `PERIOD_BASED`, must be null otherwise. fixed_dates: oneOf: - $ref: '#/components/schemas/CardDefinitionPendingPointsFixedDatesInput' - type: 'null' description: >- Fixed-dates activation. Required when `type` is `FIXED_DATES`, must be null otherwise. event_based: oneOf: - $ref: '#/components/schemas/CardDefinitionPendingPointsEventBasedInput' - type: 'null' description: >- Event-based activation. Required when `type` is `EVENT_BASED`, must be null otherwise. required: - type additionalProperties: false CardDefinitionEarningLimitsInput: type: object description: Points earning limits. properties: global: $ref: '#/components/schemas/CardDefinitionEarningLimitsGlobalInput' transactions: $ref: '#/components/schemas/CardDefinitionEarningLimitsTransactionsInput' required: - global - transactions additionalProperties: false CardDefinitionSpendingLimitsInput: type: object description: Points spending limits. properties: global: $ref: '#/components/schemas/CardDefinitionSpendingLimitsGlobalInput' transactions: $ref: '#/components/schemas/CardDefinitionSpendingLimitsTransactionsInput' required: - global - transactions additionalProperties: false CardDefinitionRefundsInput: type: object description: Refund handling configuration. properties: spent_points: $ref: '#/components/schemas/CardDefinitionRefundsSpentPointsInput' earned_points: $ref: '#/components/schemas/CardDefinitionRefundsEarnedPointsInput' required: - spent_points - earned_points additionalProperties: false CardDefinitionBalanceSettingsInput: type: object description: |- Card balance settings. `allow_negative` can only be `true` when `points_expiration.type` is `NO_EXPIRATION`. properties: allow_negative: type: boolean description: Whether the card balance is allowed to go below zero. required: - allow_negative additionalProperties: false CardDefinitionPayWithPointsInput: description: |- Pay-with-points configuration, discriminated by `type`: `NO_PAYMENTS` (paying with points disabled) or `EXCHANGE_RATIO` (points can be exchanged for money using a formula). oneOf: - type: object description: Paying with points is disabled. properties: type: type: string const: NO_PAYMENTS description: Pay-with-points type. required: - type additionalProperties: false - type: object description: Points can be exchanged for money at the configured ratio. properties: type: type: string const: EXCHANGE_RATIO description: Pay-with-points type. exchange_ratio: $ref: >- #/components/schemas/CardDefinitionPayWithPointsExchangeRatioInput required: - type - exchange_ratio additionalProperties: false discriminator: propertyName: type 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 CardDefinitionPointsExpirationRollingExpirationInput: type: object description: >- Rolling expiration configuration - points expire after a fixed period from earning. properties: period: $ref: >- #/components/schemas/CardDefinitionPointsExpirationRollingExpirationPeriodInput rounding: oneOf: - $ref: >- #/components/schemas/CardDefinitionPointsExpirationRollingExpirationRoundingInput - type: 'null' description: Optional rounding applied to the calculated expiration date. required: - period additionalProperties: false CardDefinitionPointsExpirationCalendarExpirationInput: type: object description: >- Calendar expiration configuration - points expire on fixed calendar dates. properties: expiration_dates: type: array items: $ref: >- #/components/schemas/CardDefinitionPointsExpirationCalendarExpirationDateInput minItems: 1 maxItems: 20 description: List of calendar dates on which points expire (1-20 dates). required: - expiration_dates additionalProperties: false CardDefinitionPointsExpirationSlidingExpirationInput: type: object description: >- Sliding expiration configuration - points expiration slides on member activity. At least one of `earning_activity`, `spending_activity` or `custom_activity` must be `true`. When `custom_activity` is `true`, `custom_activity_types` is required with 1-10 unique custom event schema IDs. 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 - 'null' items: type: string pattern: ^ms_[a-zA-Z0-9]+ maxItems: 10 description: >- Custom event schema IDs (pattern `^ms_[a-zA-Z0-9]+`) that reset the expiration window. Required with 1-10 unique items when `custom_activity` is `true`. period: $ref: >- #/components/schemas/CardDefinitionPointsExpirationSlidingExpirationPeriodInput required: - period additionalProperties: false CardDefinitionPendingPointsPeriodBasedInput: type: object description: >- Period-based pending points activation - points activate after a fixed period. properties: period: $ref: >- #/components/schemas/CardDefinitionPendingPointsPeriodBasedPeriodInput required: - period additionalProperties: false CardDefinitionPendingPointsFixedDatesInput: type: object description: >- Fixed-dates pending points activation - points activate on fixed calendar dates. properties: dates: type: array items: $ref: >- #/components/schemas/CardDefinitionPendingPointsFixedDatesDateInput minItems: 1 maxItems: 20 description: >- List of calendar dates on which pending points activate (1-20 dates). required: - dates additionalProperties: false CardDefinitionPendingPointsEventBasedInput: type: object description: >- Event-based pending points activation - points activate when one of the configured custom events occurs, or are cancelled after the cancel period. properties: event_types: type: array items: type: string pattern: ^ms_[a-zA-Z0-9]+ minItems: 1 maxItems: 10 description: >- Custom event schema IDs (pattern `^ms_[a-zA-Z0-9]+`) that activate pending points. 1-10 unique items. cancel_period: $ref: >- #/components/schemas/CardDefinitionPendingPointsEventBasedCancelPeriodInput required: - event_types - cancel_period additionalProperties: false CardDefinitionEarningLimitsGlobalInput: type: object description: >- Global (per card) earning limits. When `type` is `NO_LIMIT`, `limits` must be empty or `null`; when `type` is `LIMITED`, `limits` must contain exactly 1 limit. properties: type: type: string enum: - NO_LIMIT - LIMITED description: Whether global earning limits apply. limits: type: - array - 'null' items: $ref: '#/components/schemas/CardDefinitionEarningLimitsGlobalLimitInput' maxItems: 1 description: >- Limit definitions. Empty/null when `type` is `NO_LIMIT`; exactly 1 item required when `type` is `LIMITED`. required: - type additionalProperties: false CardDefinitionEarningLimitsTransactionsInput: type: object description: >- Per-transaction earning limits. When `type` is `NO_LIMIT`, `limits` must be empty or `null`; when `type` is `LIMITED`, `limits` must contain at least 1 limit. Each limit `type` may appear at most once in the array. properties: type: type: string enum: - NO_LIMIT - LIMITED description: Whether per-transaction earning limits apply. limits: type: - array - 'null' items: $ref: >- #/components/schemas/CardDefinitionEarningLimitsTransactionsLimitInput description: >- Limit definitions with unique types. Empty/null when `type` is `NO_LIMIT`; at least 1 item required when `type` is `LIMITED`. required: - type additionalProperties: false CardDefinitionSpendingLimitsGlobalInput: type: object description: >- Global (per card) spending limits. When `type` is `NO_LIMIT`, `limits` must be empty or `null`; when `type` is `LIMITED`, `limits` must contain exactly 1 limit. properties: type: type: string enum: - NO_LIMIT - LIMITED description: Whether global spending limits apply. limits: type: - array - 'null' items: $ref: '#/components/schemas/CardDefinitionSpendingLimitsGlobalLimitInput' maxItems: 1 description: >- Limit definitions. Empty/null when `type` is `NO_LIMIT`; exactly 1 item required when `type` is `LIMITED`. required: - type additionalProperties: false CardDefinitionSpendingLimitsTransactionsInput: type: object description: >- Per-transaction spending limits. When `type` is `NO_LIMIT`, `limits` must be empty or `null`; when `type` is `LIMITED`, `limits` must contain exactly 1 limit. properties: type: type: string enum: - NO_LIMIT - LIMITED description: Whether per-transaction spending limits apply. limits: type: - array - 'null' items: $ref: >- #/components/schemas/CardDefinitionSpendingLimitsTransactionsLimitInput maxItems: 1 description: >- Limit definitions. Empty/null when `type` is `NO_LIMIT`; exactly 1 item required when `type` is `LIMITED`. required: - type additionalProperties: false CardDefinitionRefundsSpentPointsInput: type: object description: >- How points spent on a refunded order are handled. When `type` is `NONE`, `methods` must be empty or `null`; when `type` is `REFUNDABLE`, `methods` must contain exactly 1 method. properties: type: type: string enum: - NONE - REFUNDABLE description: Whether spent points are refundable. methods: type: - array - 'null' items: $ref: '#/components/schemas/CardDefinitionRefundsSpentPointsMethodInput' maxItems: 1 description: >- Refund methods. Empty/null when `type` is `NONE`; exactly 1 item required when `type` is `REFUNDABLE`. Currently only one method is allowed. required: - type additionalProperties: false CardDefinitionRefundsEarnedPointsInput: type: object description: >- How points earned on a refunded order are handled. When `type` is `NONE`, `methods` must be empty or `null`; when `type` is `REFUNDABLE`, `methods` must contain exactly 1 method. properties: type: type: string enum: - NONE - REFUNDABLE description: Whether earned points are revocable on refund. methods: type: - array - 'null' items: $ref: '#/components/schemas/CardDefinitionRefundsEarnedPointsMethodInput' maxItems: 1 description: >- Revoke methods. Empty/null when `type` is `NONE`; exactly 1 item required when `type` is `REFUNDABLE`. required: - type additionalProperties: false CardDefinitionPayWithPointsExchangeRatioInput: type: object description: Exchange ratio used to convert points into money. properties: formula: oneOf: - type: string minLength: 1 maxLength: 2000 - type: number description: >- Exchange ratio formula. A string expression (1-2000 characters) or a number. Numbers are converted to strings server-side. required: - formula additionalProperties: false 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 CardDefinitionPointsExpirationRollingExpirationPeriodInput: type: object description: >- Rolling expiration period. The maximum `value` depends on `unit`: 1-90 for `DAY`, 1-12 for `MONTH`, 1-5 for `YEAR` (enforced via if/then conditions). properties: unit: type: string enum: - DAY - MONTH - YEAR description: Period unit. value: type: integer minimum: 1 maximum: 90 description: 'Period length. Maximum: 90 for `DAY`, 12 for `MONTH`, 5 for `YEAR`.' required: - unit - value additionalProperties: false CardDefinitionPointsExpirationRollingExpirationRoundingInput: type: object description: >- Rounding of the rolling expiration date. When `type` is `END_OF_PARTICULAR_MONTH`, `value` (month number 1-12) is required; for all other types `value` must be null/absent. 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 - 'null' minimum: 1 maximum: 12 description: >- Month number (1-12). Required when `type` is `END_OF_PARTICULAR_MONTH`, must be null otherwise. required: - type additionalProperties: false CardDefinitionPointsExpirationCalendarExpirationDateInput: type: object description: >- A calendar date (day + month). The maximum `day` depends on `month` (enforced via if/then conditions): 29 for February, 30 for April/June/September/November, 31 for the remaining months. properties: day: type: integer minimum: 1 maximum: 31 description: >- Day of the month. Maximum depends on the month: 29 for February, 30 for April, June, September, November, 31 otherwise. month: type: integer minimum: 1 maximum: 12 description: Month number (1-12). required: - day - month additionalProperties: false CardDefinitionPointsExpirationSlidingExpirationPeriodInput: type: object description: >- Sliding expiration period. The maximum `value` depends on `unit`: 1-90 for `DAY`, 1-12 for `MONTH`, 1-1 for `YEAR` (enforced via if/then conditions). properties: value: type: integer minimum: 1 maximum: 90 description: 'Period length. Maximum: 90 for `DAY`, 12 for `MONTH`, 1 for `YEAR`.' unit: type: string enum: - DAY - MONTH - YEAR description: Period unit. required: - value - unit additionalProperties: false CardDefinitionPendingPointsPeriodBasedPeriodInput: type: object description: >- Pending period. The maximum `value` depends on `unit`: 1-90 for `DAY`, 1-12 for `MONTH`, 1-1 for `YEAR` (enforced via if/then conditions). properties: unit: type: string enum: - DAY - MONTH - YEAR description: Period unit. value: type: integer minimum: 1 maximum: 90 description: 'Period length. Maximum: 90 for `DAY`, 12 for `MONTH`, 1 for `YEAR`.' required: - unit - value additionalProperties: false CardDefinitionPendingPointsFixedDatesDateInput: type: object description: >- A calendar date (day + month). The maximum `day` depends on `month` (enforced via if/then conditions): 29 for February, 30 for April/June/September/November, 31 for the remaining months. properties: day: type: integer minimum: 1 maximum: 31 description: >- Day of the month. Maximum depends on the month: 29 for February, 30 for April, June, September, November, 31 otherwise. month: type: integer minimum: 1 maximum: 12 description: Month number (1-12). required: - day - month additionalProperties: false CardDefinitionPendingPointsEventBasedCancelPeriodInput: type: object description: >- Period after which non-activated pending points are cancelled. The maximum `value` depends on `unit`: 1-90 for `DAY`, 1-12 for `MONTH`, 1-1 for `YEAR` (enforced via if/then conditions). properties: value: type: integer minimum: 1 maximum: 90 description: 'Period length. Maximum: 90 for `DAY`, 12 for `MONTH`, 1 for `YEAR`.' unit: type: string enum: - DAY - MONTH - YEAR description: Period unit. required: - value - unit additionalProperties: false CardDefinitionEarningLimitsGlobalLimitInput: description: >- A global earning limit, discriminated by `type`: `BALANCE_BASED` (maximum card balance) or `TIME_BASED` (maximum points earned per period). oneOf: - type: object description: Balance-based limit - the card balance cannot exceed `max` points. properties: type: type: string const: BALANCE_BASED description: Limit type. max: type: integer minimum: 1 description: Maximum card balance in points. required: - type - max additionalProperties: false - type: object description: >- Time-based limit - at most `points.max` points can be earned per period. properties: type: type: string const: TIME_BASED description: Limit type. period: $ref: >- #/components/schemas/CardDefinitionEarningLimitsGlobalTimeBasedPeriodInput points: $ref: >- #/components/schemas/CardDefinitionEarningLimitsGlobalTimeBasedPointsInput required: - type - period - points additionalProperties: false discriminator: propertyName: type CardDefinitionEarningLimitsTransactionsLimitInput: description: |- A per-transaction earning limit, discriminated by `type`: `POINTS` (maximum points earned per transaction) or `SPENDING` (minimum order amount required to earn points). oneOf: - type: object description: >- Points limit - at most `max` points can be earned in a single transaction. properties: type: type: string const: POINTS description: Limit type. max: type: integer minimum: 1 description: Maximum points earned per transaction. required: - type - max additionalProperties: false - type: object description: >- Spending threshold - points are only earned when the transaction amount is at least `min_amount`. properties: type: type: string const: SPENDING description: Limit type. min_amount: type: integer minimum: 1 description: Minimum transaction amount required to earn points. required: - type - min_amount additionalProperties: false discriminator: propertyName: type CardDefinitionSpendingLimitsGlobalLimitInput: description: >- A global spending limit, discriminated by `type`: `SPENDING_BASED` (total points spent) or `TIME_BASED` (points spent per period). oneOf: - type: object description: Spending-based limit - at most `max` points can be spent in total. properties: type: type: string const: SPENDING_BASED description: Limit type. max: type: integer minimum: 1 description: Maximum total points spent. required: - type - max additionalProperties: false - type: object description: >- Time-based limit - at most `points.max` points can be spent per period. properties: type: type: string const: TIME_BASED description: Limit type. period: $ref: >- #/components/schemas/CardDefinitionSpendingLimitsGlobalTimeBasedPeriodInput points: $ref: >- #/components/schemas/CardDefinitionSpendingLimitsGlobalTimeBasedPointsInput required: - type - period - points additionalProperties: false discriminator: propertyName: type CardDefinitionSpendingLimitsTransactionsLimitInput: description: >- A per-transaction spending limit. Currently only the `POINTS` type is supported. oneOf: - type: object description: >- Points limit - at most `max` points can be spent in a single transaction. properties: type: type: string const: POINTS description: Limit type. max: type: integer minimum: 1 description: Maximum points spent per transaction. required: - type - max additionalProperties: false discriminator: propertyName: type CardDefinitionRefundsSpentPointsMethodInput: description: >- A spent points refund method. Currently only the `RETURN_POINTS` type is supported. oneOf: - type: object description: Return spent points back to the card. properties: type: type: string const: RETURN_POINTS description: Refund method type. mode: type: string enum: - REFUND_ALL - REFUND_ITEM - REFUND_AMOUNT description: >- Refund mode: on full-order refund (`REFUND_ALL`), per-item refund (`REFUND_ITEM`) or amount-based refund (`REFUND_AMOUNT`). required: - type - mode additionalProperties: false discriminator: propertyName: type CardDefinitionRefundsEarnedPointsMethodInput: description: >- An earned points revoke method, discriminated by `type`: `REVOKE_FROM_PENDING` (only valid when `pending_points.type` is `PERIOD_BASED`, `FIXED_DATES` or `EVENT_BASED`) 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 additionalProperties: false - 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. `REVOKE_BELOW_ZERO` requires `balance_settings.allow_negative` to be `true`. required: - type - mode additionalProperties: false discriminator: propertyName: type 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 CardDefinitionEarningLimitsGlobalTimeBasedPeriodInput: type: object description: >- Time-based earning limit period. When `type` is `CURRENT_PERIOD` (the only allowed value), `current_period` is required. properties: type: type: string enum: - CURRENT_PERIOD description: >- Period type. Currently only `CURRENT_PERIOD` (current calendar period) is supported. current_period: oneOf: - $ref: >- #/components/schemas/CardDefinitionEarningLimitsGlobalTimeBasedCurrentPeriodInput - type: 'null' description: >- Current-period configuration. Required when `type` is `CURRENT_PERIOD`. required: - type additionalProperties: false CardDefinitionEarningLimitsGlobalTimeBasedPointsInput: type: object description: Points cap for the time-based earning limit. properties: max: type: integer minimum: 1 maximum: 9007199254740991 description: >- Maximum points that can be earned within the period (1 to 9007199254740991). required: - max additionalProperties: false CardDefinitionSpendingLimitsGlobalTimeBasedPeriodInput: type: object description: >- Time-based spending limit period. When `type` is `CURRENT_PERIOD` (the only allowed value), `current_period` is required. properties: type: type: string enum: - CURRENT_PERIOD description: >- Period type. Currently only `CURRENT_PERIOD` (current calendar period) is supported. current_period: oneOf: - $ref: >- #/components/schemas/CardDefinitionSpendingLimitsGlobalTimeBasedCurrentPeriodInput - type: 'null' description: >- Current-period configuration. Required when `type` is `CURRENT_PERIOD`. required: - type additionalProperties: false CardDefinitionSpendingLimitsGlobalTimeBasedPointsInput: type: object description: Points cap for the time-based spending limit. properties: max: type: integer minimum: 1 maximum: 9007199254740991 description: >- Maximum points that can be spent within the period (1 to 9007199254740991). required: - max additionalProperties: false 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 CardDefinitionEarningLimitsGlobalTimeBasedCurrentPeriodInput: type: object description: Calendar period unit used to reset the time-based earning limit. properties: unit: type: string enum: - DAY - WEEK - MONTH - QUARTER - YEAR description: Calendar period unit. required: - unit additionalProperties: false CardDefinitionSpendingLimitsGlobalTimeBasedCurrentPeriodInput: type: object description: Calendar period unit used to reset the time-based spending limit. properties: unit: type: string enum: - DAY - WEEK - MONTH - QUARTER - YEAR description: Calendar period unit. required: - unit additionalProperties: false 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 ````