Sign in

v1

latestOpenAPI 3.0.1MIT2026-07-263151,3912.3 MB
Card Definitions

Create Card Definition

<Warning>

<Badge color="yellow">BETA endpoint</Badge>

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.

</Warning>

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.
post/v2/loyalties/card-definitions

Request body

namestring required

Card definition name.

type'INDIVIDUAL' required

Card definition type. Currently only INDIVIDUAL is supported.

{"stackTrail":"components:schemas:CardDefinitionCreateRequest:properties:status","oasType":"schema","type":"unknown","description":"Initial status. Allowed values on create are `DRAFT` and `ACTIVE`. Defaults to `DRAFT` when omitted."}
{"stackTrail":"components:schemas:CardDefinitionCreateRequest:properties:metadata","oasType":"schema","type":"unknown","description":"Arbitrary key-value metadata attached to the card definition."}

Response

The created card definition.

idstring required

Unique card definition ID.

namestring required

Card definition name.

type'INDIVIDUAL' required

Card definition type.

status'DRAFT' | 'ACTIVE' | 'DELETED' required

Current card definition status.

metadataobject required

Arbitrary key-value metadata. Empty object when not set.

created_atstring date-time required

Creation timestamp (ISO 8601).

updated_atstring date-time required

Last update timestamp (ISO 8601). Null when the card definition has never been updated.

objectstring required

Object type marker. Always card_definition.