> ## 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.

# Discount code import

> Learn how to import codes to Voucherify

export const DownloadLink = ({url, filename, children}) => {
  const handleDownload = async e => {
    e.preventDefault();
    try {
      const response = await fetch(url);
      const blob = await response.blob();
      const blobUrl = window.URL.createObjectURL(blob);
      const link = document.createElement('a');
      link.href = blobUrl;
      link.download = filename;
      document.body.appendChild(link);
      link.click();
      document.body.removeChild(link);
      window.URL.revokeObjectURL(blobUrl);
    } catch (error) {
      window.open(url, '_blank');
    }
  };
  return <a href={url} onClick={handleDownload} style={{
    cursor: 'pointer',
    fontWeight: 'bold'
  }}>
      {children}
    </a>;
};

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 coupons
* New unique coupons to a campaign.
* Existing coupons to update them.

<Info>
  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.
</Info>

<Note>
  <Badge color="blue">Important</Badge>

  * 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.
</Note>

## Preparing CSV file for generic coupons

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

Use the <DownloadLink url="https://raw.githubusercontent.com/voucherifyio/voucherify-openapi/refs/heads/master/documentation/examples/import-generic-coupons-template.csv" filename="import-generic-coupons-template.csv">CSV generic coupon file template</DownloadLink>.

### Required fields

* **Code**\
  A unique discount coupon code.\
  You cannot import two identical codes into a single Voucherify project.

* **Voucher Type**\
  Defines the voucher type.\
  For discount coupons, the value must be `DISCOUNT_VOUCHER`.

* **Value**\
  The discount value.\
  Must be provided as an integer number.

* **Discount Type**\
  Defines how the discount value is interpreted.\
  Supported values:
  * `AMOUNT` – fixed amount discount
  * `PERCENT` – percentage discount
  * `FIXED` – fixed price
  * `UNIT` – discount applied per item unit

### Optional fields

* **Discount effect**\
  Defines how the discount is applied to the order.\
  Supported values:
  * `APPLY_TO_ORDER` – applies the discount to the entire order total
  * `APPLY_TO_ITEMS` – applies the discount to selected items only
  * `APPLY_TO_ITEMS_PROPORTIONALLY` – distributes the discount proportionally across item values
  * `APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY` – distributes the discount proportionally based on item quantities
  * `APPLY_TO_ITEMS_BY_QUANTITY` – applies the discount to a specific number of eligible items

<Warning>
  For effects that contain `_ITEMS_`, a validation rule is required.\
  Without a validation rule, the discount will not be applied to products.
</Warning>

* **Validation rule ID**\
  The ID of a validation rule that governs how and when the coupon can be redeemed.\
  The rule is automatically applied to the imported coupon.

* **Category**\
  A custom tag assigned to the coupon.\
  Categories help you filter and organize coupons in the Dashboard.

* **Active**\
  Enables or disables the coupon.\
  Accepted values: `TRUE` or `FALSE`.\
  An inactive coupon cannot be redeemed, even if it is within its validity timeframe.

* **Start date**\
  The date when the coupon becomes valid.\
  It must follow the ISO 8601 format, for example: `2022-09-19T00:00:00.000Z`.

* **Expiration date**\
  The date when the coupon expires.\
  It must follow the ISO 8601 format, for example: `2022-11-30T00:00:00.000Z`.

* **Redeemed quantity**\
  The number of times the coupon has already been redeemed.\
  If omitted, the value defaults to `0`.

* **Redeemed amount**\
  The total discount amount already redeemed using this coupon.

* **Redemption limit**\
  The maximum number of redemptions allowed.\
  If omitted, the redemption limit is set to unlimited.

* **Additional info**\
  Any additional information you want to store with the coupon.\
  This field is informational only.

* **Formula**\
  A dynamic discount formula applied to the coupon.\
  Provide the *Expression Output* of an existing formula.

* **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.

<Note>
  Fields other than the ones listed above will not be imported. Even if you provide them, they will be skipped.
</Note>

These codes will function as standalone discount coupons, independent of a campaign.

### Import generic coupons

Go to **Campaign hub** > **Campaigns** and **Import CSV**.

<Info>
  <Badge color="gray">Webhook sendout prerequisite</Badge>

  While 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](/api-reference/voucher/created) or [Voucher updated](/api-reference/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](/api-reference/project-settings-webhooks) to learn more about configuring webhooks.
</Info>

<Steps>
  <Step title="Upload CSV file">
    Upload your prepared CSV file.

    Once uploaded, you'll see an overview of first rows and columns of the file.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Complete the import">
    Once ready, **Import** and wait for notification when the import is complete.
  </Step>
</Steps>

<Note>
  For large imports, the process can take a significant amount of time.
</Note>

## Preparing CSV file for campaign discount coupons

<Info>
  <Badge color="gray">Import coupons to campaign prerequisite</Badge>

  If you don't have a campaign for your codes yet, [create a discount coupon campaign](/build/create-discount-coupons) first.
</Info>

Use these fields when importing discount coupons **into an existing campaign**.\
Imported coupons inherit all campaign settings unless explicitly overridden.

Use the <DownloadLink url="https://raw.githubusercontent.com/voucherifyio/voucherify-openapi/refs/heads/master/documentation/examples/import-discount-coupons-into-campaign-template.csv" filename="import-discount-coupons-into-campaign-template.csv">CSV discount coupon file template</DownloadLink>.

### Required fields

* **Code**\
  A unique discount coupon code.

### Optional fields

* **Active**\
  Enables or disables the coupon.\
  Accepted values: `TRUE` or `FALSE`.

  Import behavior:

  * If the campaign is **Active** and the `active` field is omitted, imported coupons are set to `TRUE`.
  * If the campaign is **Expired** and the `active` field is omitted, imported coupons are set to `FALSE`.

* **Category**\
  A custom tag assigned to the coupon for filtering and organization.

* **Redeemed quantity**\
  The number of times the coupon has already been redeemed.

* **Start date**\
  The date when the coupon becomes valid.\
  Must follow the ISO 8601 format.

* **Expiration date**\
  The date when the coupon expires.\
  Must follow the ISO 8601 format.

* **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 coupon 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.

<Note>
  Fields other than the ones listed above will not be imported. Even if you provide them, they will be skipped.
</Note>

All unmapped attributes will inherit the campaign’s default settings as well as validation rules, time frame, redemption limits, and so on.

### Import discount coupons to a campaign

In **Campaign hub** > **Campaigns**, go to the discount campaign where you want to import the coupons. In the top right corner, use the three-dot menu to **Import CSV file**.

<Steps>
  <Step title="Upload CSV file">
    Upload your prepared CSV file.

    Once uploaded, you'll see an overview of first rows and columns of the file.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Complete the import">
    Once ready, **Import** and wait for notification when the import is complete.
  </Step>
</Steps>

<Note>
  For large imports, the process can take a significant amount of time.
</Note>

New discount coupons will be visible in the **Vouchers** tab in the detailed campaign view.