Skip to main content
If you need to share codes from other sources with Voucherify, you can handle this scenario using the Import CSV tool in the Dashboard. The tool enables you to import:
  • Generic gift cards.
  • New unique gift cards to a campaign.
  • Existing gift cards to update them.
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 norms, 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 generic gift cards

Use these fields when importing standalone (generic) gift cards. Generic gift cards are not assigned to a campaign and work independently.

​
Required fields

  • Voucher Type
    Defines the voucher type.
    For gift cards, the value must be GIFT_VOUCHER.
  • Code
    A unique gift card code.
    You cannot import two identical codes into a single Voucherify project.
  • Value
    The initial gift card balance.

​
Optional fields

  • Active
    Enables or disables the gift card.
    Accepted values: TRUE or FALSE.
    An inactive gift card cannot be redeemed, even if it is within its validity timeframe.
  • Start date
    The date when the gift card becomes valid.
    Must follow the ISO 8601 format, for example:
    2022-09-19T00:00:00.000Z.
  • Expiration date
    The date when the gift card expires.
    Must follow the ISO 8601 format, for example:
    2022-11-30T00:00:00.000Z.
  • Category
    A custom tag assigned to the gift card.
    Categories help you filter and organize codes in the Dashboard.
  • Redemption limit
    The maximum number of times the gift card can be redeemed.
    If omitted, the redemption limit is set to unlimited.
  • Redeemed quantity
    The number of times the gift card has already been redeemed.
    If omitted, the value defaults to 0.
  • Additional Info
    Any additional information you want to store with the gift card.
    This field is informational only.
  • 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.
Fields other than the ones listed above will not be imported. Even if you provide them, they will be skipped.CSV generic gift card file template
These codes will function as standalone gift cards, independent of a campaign.

​
Import generic gift cards

Go to Campaign hub > Campaigns and Import CSV.
Webhook sendout prerequisiteWhile importing, you can additionally select the checkbox to Create a webhook sendout for the vouchers created and updated during the import. This triggers a Voucher created or Voucher updated webhook when the coupons are processed.To enable webhook sendout during the voucher import, first configure webhooks in Project settings > Webhooks. Select the voucher.created and voucher.updated events for the sendout to work.Read Project settings webhooks to learn more about configuring webhooks.
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.

​
Preparing CSV file for campaign gift cards

Import gift cards to campaign prerequisiteIf you don’t have a campaign for your codes yet, create a gift card campaign first.
Use these fields when importing gift cards into an existing gift card campaign.
Imported gift cards inherit all campaign settings unless explicitly overridden.

​
Required fields

  • Code
    A unique gift card code.

​
Optional fields

  • Active
    Enables or disables the gift card.
    Accepted values: TRUE or FALSE.     Import behavior:
    • If the campaign is Active and the active field is omitted, imported gift cards are set to TRUE.
    • If the campaign is Expired and the active field is omitted, imported gift cards are set to FALSE.
  • Category
    A custom tag assigned to the gift card for filtering and organization.
  • Gift amount
    The initial gift card balance.
    If omitted, the campaign default balance is applied.
  • Start date The date and time when the gift card becomes active. Accepted format: ISO 8601 (e.g., YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ). If omitted, the gift card is active immediately upon creation.
  • Expiration date The date and time when the gift card is no longer valid for redemption. Accepted format: ISO 8601. Once this date passes, the gift card status automatically changes to Expired.
  • Redeemed quantity
    The number of times the gift card has already been redeemed.
  • Redeemed amount
    The amount already redeemed from the available gift card balance.
  • 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 gift card 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.CSV gift card file template
All unmapped attributes will inherit the campaign’s default settings as well as validation rules, time frame, redemption limits, and so on.

​
Import behavior for selected attributes

Some of the attributes work as follows when imported:
  • Active:
    • If the campaign is Active and the active field is omitted in the CSV, the active attribute for the imported vouchers is set to TRUE.
    • If the campaign is Expired and the active field is omitted in the CSV, the active attribute for the imported vouchers is set to FALSE.
  • Metadata:
    • If metadata is omitted, the voucher inherits the campaign’s metadata.
    • If metadata columns are added, the mapped metadata only overrides those specific fields.

​
Import gift cards to a campaign

In Campaign hub > Campaigns, go to the gift card campaign where you want to import the cards. 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 9, 2026