Skip to main content
POST
/
v2
/
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>",
  "type": "INDIVIDUAL",
  "status": "DRAFT",
  "code_config": {
    "length": 123,
    "charset": "<string>",
    "prefix": "<string>",
    "postfix": "<string>",
    "pattern": "<string>"
  },
  "points_expiration": {
    "type": "NO_EXPIRATION",
    "rolling_expiration": {
      "period": {
        "unit": "DAY",
        "value": 2
      },
      "rounding": {
        "type": "END_OF_MONTH",
        "value": 6
      }
    },
    "calendar_expiration": {
      "expiration_dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "sliding_expiration": {
      "period": {
        "value": 2,
        "unit": "DAY"
      },
      "earning_activity": true,
      "spending_activity": true,
      "custom_activity": true,
      "custom_activity_types": [
        "<string>"
      ]
    }
  },
  "pending_points": {
    "type": "IMMEDIATE",
    "period_based": {
      "period": {
        "unit": "DAY",
        "value": 2
      }
    },
    "fixed_dates": {
      "dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "event_based": {
      "event_types": [
        "<string>"
      ],
      "cancel_period": {
        "value": 2,
        "unit": "DAY"
      }
    }
  },
  "earning_limits": {
    "global": {
      "type": "NO_LIMIT",
      "limits": [
        {
          "type": "BALANCE_BASED",
          "max": 2
        }
      ]
    },
    "transactions": {
      "type": "NO_LIMIT",
      "limits": [
        {
          "type": "POINTS",
          "max": 2,
          "min_amount": 2
        }
      ]
    }
  },
  "spending_limits": {
    "global": {
      "type": "NO_LIMIT",
      "limits": [
        {
          "type": "SPENDING_BASED",
          "max": 2
        }
      ]
    },
    "transactions": {
      "type": "NO_LIMIT",
      "limits": [
        {
          "type": "POINTS",
          "max": 2
        }
      ]
    }
  },
  "refunds": {
    "spent_points": {
      "type": "NONE",
      "methods": [
        {
          "type": "RETURN_POINTS",
          "mode": "REFUND_ALL"
        }
      ]
    },
    "earned_points": {
      "type": "NONE",
      "methods": [
        {
          "type": "REVOKE_FROM_PENDING",
          "mode": "REVOKE_TO_ZERO"
        }
      ]
    }
  },
  "balance_settings": {
    "allow_negative": true
  },
  "metadata": {}
}
'
{
  "id": "<string>",
  "name": "<string>",
  "type": "INDIVIDUAL",
  "status": "DRAFT",
  "code_config": {
    "pattern": "<string>",
    "length": 123,
    "charset": "<string>",
    "prefix": "<string>",
    "postfix": "<string>"
  },
  "points_expiration": {
    "type": "NO_EXPIRATION",
    "rolling_expiration": {
      "period": {
        "value": 2,
        "unit": "DAY"
      },
      "rounding": {
        "type": "END_OF_MONTH",
        "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,
        "unit": "DAY"
      }
    }
  },
  "pending_points": {
    "type": "IMMEDIATE",
    "period_based": {
      "period": {
        "value": 2,
        "unit": "DAY"
      }
    },
    "fixed_dates": {
      "dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "event_based": {
      "event_types": [
        "<string>"
      ],
      "cancel_period": {
        "value": 2,
        "unit": "DAY"
      }
    }
  },
  "earning_limits": {
    "global": {
      "type": "NO_LIMIT",
      "limits": [
        {
          "type": "BALANCE_BASED",
          "max": 2,
          "period": {
            "type": "CURRENT_PERIOD",
            "current_period": {
              "unit": "DAY"
            }
          },
          "points": {
            "max": 1073741824
          }
        }
      ]
    },
    "transactions": {
      "type": "NO_LIMIT",
      "limits": [
        {
          "type": "POINTS",
          "max": 2,
          "min_amount": 2
        }
      ]
    }
  },
  "spending_limits": {
    "global": {
      "type": "NO_LIMIT",
      "limits": [
        {
          "type": "SPENDING_BASED",
          "max": 2,
          "period": {
            "type": "CURRENT_PERIOD",
            "current_period": {
              "unit": "DAY"
            }
          },
          "points": {
            "max": 1073741824
          }
        }
      ]
    },
    "transactions": {
      "type": "NO_LIMIT",
      "limits": [
        {
          "type": "POINTS",
          "max": 2
        }
      ]
    }
  },
  "refunds": {
    "spent_points": {
      "type": "NONE",
      "methods": [
        {
          "type": "RETURN_POINTS",
          "mode": "REFUND_ALL"
        }
      ]
    },
    "earned_points": {
      "type": "NONE",
      "methods": [
        {
          "type": "REVOKE_FROM_PENDING",
          "mode": "REVOKE_TO_ZERO"
        }
      ]
    }
  },
  "balance_settings": {
    "allow_negative": true
  },
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "object": "<string>",
  "updated_at": "2023-11-07T05:31:56Z"
}

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.

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.

​
points_expiration
object

Points expiration policy. Defaults to NO_EXPIRATION.

​
pending_points
object

Pending points policy. Defaults to IMMEDIATE.

​
earning_limits
object

Earning limits configuration. Defaults to no limits.

​
spending_limits
object

Spending limits configuration. Defaults to no limits.

​
refunds
object

Refund policies. Defaults to no refunds.

​
balance_settings
object

Balance settings. Defaults to allow_negative: false.

​
metadata
object

Response

Created card definition

Full card definition DTO returned by all CRUD endpoints.

​
id
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
​
points_expiration
object
required
​
pending_points
object
required
​
earning_limits
object
required
​
spending_limits
object
required
​
refunds
object
required
​
balance_settings
object
required
​
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 May 11, 2026