Create Card Definition

curl --request POST \
  --url https://api.voucherify.io/v2/loyalties/card-definitions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "name": "<string>",
  "status": "DRAFT",
  "code_config": {
    "length": 123,
    "charset": "<string>",
    "prefix": "<string>",
    "postfix": "<string>",
    "pattern": "<string>"
  },
  "points_expiration": {
    "rolling_expiration": {
      "period": {
        "value": 2
      },
      "rounding": {
        "value": 6
      }
    },
    "calendar_expiration": {
      "expiration_dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "sliding_expiration": {
      "period": {
        "value": 2
      },
      "earning_activity": true,
      "spending_activity": true,
      "custom_activity": true,
      "custom_activity_types": [
        "<string>"
      ]
    }
  },
  "pending_points": {
    "period_based": {
      "period": {
        "value": 2
      }
    },
    "fixed_dates": {
      "dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "event_based": {
      "event_types": [
        "<string>"
      ],
      "cancel_period": {
        "value": 2
      }
    }
  },
  "earning_limits": {
    "global": {
      "limits": [
        {
          "max": 2
        }
      ]
    },
    "transactions": {
      "limits": [
        {
          "max": 2,
          "min_amount": 2
        }
      ]
    }
  },
  "spending_limits": {
    "global": {
      "limits": [
        {
          "max": 2
        }
      ]
    },
    "transactions": {
      "limits": [
        {
          "max": 2
        }
      ]
    }
  },
  "refunds": {
    "spent_points": {
      "methods": [
        {}
      ]
    },
    "earned_points": {
      "methods": [
        {}
      ]
    }
  },
  "balance_settings": {
    "allow_negative": true
  },
  "metadata": {}
}
'

{
  "id": "<string>",
  "name": "<string>",
  "code_config": {
    "pattern": "<string>",
    "length": 123,
    "charset": "<string>",
    "prefix": "<string>",
    "postfix": "<string>"
  },
  "points_expiration": {
    "rolling_expiration": {
      "period": {
        "value": 2
      },
      "rounding": {
        "value": 6
      }
    },
    "calendar_expiration": {
      "expiration_dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "sliding_expiration": {
      "earning_activity": true,
      "spending_activity": true,
      "custom_activity": true,
      "custom_activity_types": [
        "<string>"
      ],
      "period": {
        "value": 2
      }
    }
  },
  "pending_points": {
    "period_based": {
      "period": {
        "value": 2
      }
    },
    "fixed_dates": {
      "dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "event_based": {
      "event_types": [
        "<string>"
      ],
      "cancel_period": {
        "value": 2
      }
    }
  },
  "earning_limits": {
    "global": {
      "limits": [
        {
          "max": 2,
          "period": {
            "current_period": {}
          },
          "points": {
            "max": 1073741824
          }
        }
      ]
    },
    "transactions": {
      "limits": [
        {
          "max": 2,
          "min_amount": 2
        }
      ]
    }
  },
  "spending_limits": {
    "global": {
      "limits": [
        {
          "max": 2,
          "period": {
            "current_period": {}
          },
          "points": {
            "max": 1073741824
          }
        }
      ]
    },
    "transactions": {
      "limits": [
        {
          "max": 2
        }
      ]
    }
  },
  "refunds": {
    "spent_points": {
      "methods": [
        {}
      ]
    },
    "earned_points": {
      "methods": [
        {}
      ]
    }
  },
  "balance_settings": {
    "allow_negative": true
  },
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "object": "<string>",
  "updated_at": "2023-11-07T05:31:56Z"
}

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 subject to change. If you want to share feedback or improvements, contact Voucherify support or your Technical Account Manager.

Creates a new card definition with the specified configuration.

Required fields: name, type. All other fields have sensible defaults. The code_config is optional on input but required internally (defaults are generated).

Custom validators applied:

createCardDefinitionBalanceSettings: balance_settings.allow_negative can only be true when points_expiration.type is NO_EXPIRATION.
createCardDefinitionRefunds: refunds.earned_points.methods with type REVOKE_BELOW_ZERO requires balance_settings.allow_negative: true. Method type REVOKE_FROM_PENDING requires pending_points.type to be one of PERIOD_BASED, FIXED_DATES, or EVENT_BASED.

POST

loyalties

card-definitions

Create Card Definition

curl --request POST \
  --url https://api.voucherify.io/v2/loyalties/card-definitions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "name": "<string>",
  "status": "DRAFT",
  "code_config": {
    "length": 123,
    "charset": "<string>",
    "prefix": "<string>",
    "postfix": "<string>",
    "pattern": "<string>"
  },
  "points_expiration": {
    "rolling_expiration": {
      "period": {
        "value": 2
      },
      "rounding": {
        "value": 6
      }
    },
    "calendar_expiration": {
      "expiration_dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "sliding_expiration": {
      "period": {
        "value": 2
      },
      "earning_activity": true,
      "spending_activity": true,
      "custom_activity": true,
      "custom_activity_types": [
        "<string>"
      ]
    }
  },
  "pending_points": {
    "period_based": {
      "period": {
        "value": 2
      }
    },
    "fixed_dates": {
      "dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "event_based": {
      "event_types": [
        "<string>"
      ],
      "cancel_period": {
        "value": 2
      }
    }
  },
  "earning_limits": {
    "global": {
      "limits": [
        {
          "max": 2
        }
      ]
    },
    "transactions": {
      "limits": [
        {
          "max": 2,
          "min_amount": 2
        }
      ]
    }
  },
  "spending_limits": {
    "global": {
      "limits": [
        {
          "max": 2
        }
      ]
    },
    "transactions": {
      "limits": [
        {
          "max": 2
        }
      ]
    }
  },
  "refunds": {
    "spent_points": {
      "methods": [
        {}
      ]
    },
    "earned_points": {
      "methods": [
        {}
      ]
    }
  },
  "balance_settings": {
    "allow_negative": true
  },
  "metadata": {}
}
'

{
  "id": "<string>",
  "name": "<string>",
  "code_config": {
    "pattern": "<string>",
    "length": 123,
    "charset": "<string>",
    "prefix": "<string>",
    "postfix": "<string>"
  },
  "points_expiration": {
    "rolling_expiration": {
      "period": {
        "value": 2
      },
      "rounding": {
        "value": 6
      }
    },
    "calendar_expiration": {
      "expiration_dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "sliding_expiration": {
      "earning_activity": true,
      "spending_activity": true,
      "custom_activity": true,
      "custom_activity_types": [
        "<string>"
      ],
      "period": {
        "value": 2
      }
    }
  },
  "pending_points": {
    "period_based": {
      "period": {
        "value": 2
      }
    },
    "fixed_dates": {
      "dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "event_based": {
      "event_types": [
        "<string>"
      ],
      "cancel_period": {
        "value": 2
      }
    }
  },
  "earning_limits": {
    "global": {
      "limits": [
        {
          "max": 2,
          "period": {
            "current_period": {}
          },
          "points": {
            "max": 1073741824
          }
        }
      ]
    },
    "transactions": {
      "limits": [
        {
          "max": 2,
          "min_amount": 2
        }
      ]
    }
  },
  "spending_limits": {
    "global": {
      "limits": [
        {
          "max": 2,
          "period": {
            "current_period": {}
          },
          "points": {
            "max": 1073741824
          }
        }
      ]
    },
    "transactions": {
      "limits": [
        {
          "max": 2
        }
      ]
    }
  },
  "refunds": {
    "spent_points": {
      "methods": [
        {}
      ]
    },
    "earned_points": {
      "methods": [
        {}
      ]
    }
  },
  "balance_settings": {
    "allow_negative": true
  },
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "object": "<string>",
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

X-App-Id

string

header

required

X-App-Token

string

header

required

Body

application/json

name

string

required

Required string length: 1 - 200

type

enum<string>

required

Available options:

INDIVIDUAL

status

enum<string> | null

default:DRAFT

Initial status. Defaults to DRAFT if not provided.

Available options:

DRAFT,

ACTIVE,

null

code_config

object

Code generation configuration. Defaults to 10-character alphanumeric pattern if not provided.

Show child attributes

points_expiration

object

Points expiration policy. Defaults to NO_EXPIRATION.

Show child attributes

pending_points

object

Pending points policy. Defaults to IMMEDIATE.

Show child attributes

earning_limits

object

Earning limits configuration. Defaults to no limits.

Show child attributes

spending_limits

object

Spending limits configuration. Defaults to no limits.

Show child attributes

refunds

object

Refund policies. Defaults to no refunds.

Show child attributes

balance_settings

object

Balance settings. Defaults to allow_negative: false.

Show child attributes

metadata

object

Response

Created card definition

Full card definition DTO returned by all CRUD endpoints.

string

required

name

string

required

type

enum<string>

required

Available options:

INDIVIDUAL

status

enum<string>

required

Available options:

DRAFT,

ACTIVE,

INACTIVE,

DELETED

code_config

object

required

Show child attributes

points_expiration

object

required

Show child attributes

pending_points

object

required

Show child attributes

earning_limits

object

required

Show child attributes

spending_limits

object

required

Show child attributes

refunds

object

required

Show child attributes

balance_settings

object

required

Show child attributes

metadata

object

required

created_at

string<date-time>

required

object

string

required

Allowed value: "card_definition"

updated_at

string<date-time> | null

Last modified on June 2, 2026

List Card Definitions Get Card Definition

⌘I