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

# Loyalty card import

> Learn how to import loyalty cards 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 migrate loyalty cards from another system, you can use the **Import CSV tool** in the Dashboard.

The tool enables you to:

* Import new loyalty cards to a campaign.
* Update selected attributes of existing loyalty cards.

<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 loyalty cards

<Info>
  <Badge color="gray">Import loyalty cards: Prerequisite</Badge>

  Before importing loyalty cards, create a [loyalty program](/build/create-loyalty-campaign).
</Info>

Loyalty cards must be imported into an existing loyalty campaign.

Imported cards inherit campaign settings unless explicitly set up in the CSV file.

Use the <DownloadLink url="https://raw.githubusercontent.com/voucherifyio/voucherify-openapi/refs/heads/master/documentation/examples/import-loyalty-cards-into-campaign-template.csv" filename="import-loyalty-cards-into-campaign-template.csv">CSV loyalty card file template</DownloadLink> for faster preparation.

### Required fields

* **Code**\
  A unique loyalty card code.\
  You can't import two identical codes into a single Voucherify project.

### Optional fields

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

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

  Import behavior:

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

* **Loyalty points**\
  The initial number of points assigned to the card.

  Important:

  * Points are applied only to newly imported cards.
  * Points of existing cards can't be updated through CSV import.

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

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

* **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 loyalty card inherits campaign 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 inherit the campaign’s default settings, including validation rules, earning rules, expiration policy, and other campaign-level configurations.

## Import loyalty cards to a campaign

In **Campaign hub** > **Campaigns**, open your loyalty program.

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 loyalty codes will be visible in the **Loyalty cards** tab in the detailed campaign view.