Skip to main content
If you need to migrate referral codes from another system, you can use the Import CSV tool in the Dashboard. The tool enables you to:
  • Import new referral codes into a campaign.
  • Update selected attributes of existing referral codes.
When importing codes to a campaign, the system applies two simultaneous limits for the import file:
  • Code count limit: Up to 100,000 codes.
  • File size limit: Up to 10 MB CSV file size.
The import will stop when whichever limit hits first.Note that 100,000 codes is the overall campaign code limit. If the campaign already contains codes (e.g., 50,000 codes), only the remaining capacity (e.g., 50,000 codes) will be imported to maintain the 100,000 total code limit.
Important
  • The start and expiration dates in the CSV file should be provided in compliance with the ISO 8601 standard, for example, 2020-03-11T09:00:00.000Z.
  • CSV columns mapped to custom attributes will be added as code metadata. The number of custom attributes you can import as metadata is unlimited.
  • You cannot import two identical codes to a single Voucherify project.
  • When importing existing incentives (discount coupons, referral codes, loyalty cards, or gift cards) into a campaign, only two fields can be updated: the active status (true/false) and the category. All other attributes remain unchanged.

​
Preparing CSV file for referral codes

Referral campaign prerequisiteBefore importing, create a referral campaign in Voucherify.
Referral codes can only be imported into an existing referral campaign. Imported codes inherit campaign settings unless explicitly overridden. Use the CSV referral code file template for faster preparation.

​
Required fields

  • Code: A unique referral code value. You cannot import two identical codes into a single Voucherify project.

​
Optional fields

  • Active
    Enables or disables the referral code.
    Accepted values: TRUE or FALSE.     Import behavior:
    • If the campaign is Active and the active field is omitted, imported codes are set to TRUE.
    • If the campaign is Expired and the active field is omitted, imported codes are set to FALSE.
  • Category
    A custom tag assigned to the referral code for filtering and organization.
  • Redeemed quantity
    The number of times the referral code has already been redeemed. If omitted, the value defaults to 0. This works only for new codes.
  • Start date The date and time when the referral code becomes active. Accepted format: ISO 8601 (e.g., YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ). If omitted, the referral code is active immediately upon creation.
  • Expiration date The date and time when the referral code is no longer valid for redemption. Accepted format: ISO 8601. Once this date passes, the referral code status automatically changes to Expired.
  • Metadata (custom attributes) Metadata allows you to add custom information to Voucherify objects. There are two ways to handle it:
    • Metadata (Schema): These are fields you define in Project settings > Metadata schema. You choose the data type (like string or number) and if the field is mandatory. This ensures your metadata is consistent.
    • Metadata (Unknown): These are fields sent to Voucherify without being defined first (through the API, imports, or manual entry). They are always treated as simple text strings. They are useful for one-time metadata, but they do not support advanced filtering or strict validation.
    Metadata import behavior:
    • If metadata columns are omitted, the referral code inherits the campaign’s metadata.
    • If metadata columns are added and mapped, only those specific fields are overridden.
    • Metadata that is not mapped remains unchanged.
Fields other than the ones listed above will not be imported. Even if you provide them, they will be skipped.
All unmapped attributes inherit the campaign’s default settings, including validation rules, reward logic, and time limits.

​
Updating existing referral codes

You can re-import existing referral codes to update them. When importing existing referral codes:
  • Only Active status and Category can be updated.
  • Other attributes remain unchanged.
Referral code values cannot be changed. To replace a code, create a new one.

​
Import referral codes to a campaign

In Campaign hub > Campaigns, open your referral campaign. In the top-right corner, use the three-dot menu to Import CSV file.
1

Upload CSV file

Upload your prepared CSV file.Once uploaded, you’ll see an overview of first rows and columns of the file.
2

Map fields

In Map Fields, select for each CSV column:
  • Do not map to skip that column.
  • Voucherify fields to Select Voucherify properties, like Code, Voucher type, and so on.
  • Metadata (Schema) to map a given column to custom attributes that are defined for vouchers.
  • Metadata (Unknown) to map to an undefined custom attribute key.
3

Complete the import

Once ready, Import and wait for notification when the import is complete.
For large imports, the process can take a significant amount of time.
Last modified on February 24, 2026