# Import coupons

> If you are replacing an existing coupon or voucher system with Talon.One, you can migrate coupon codes from the old system to Talon.One. This ensures the legacy codes continue to work.

> For the complete documentation index, see [llms.txt](https://docs.talon.one/llms.txt).

:::tip Overview

You can import coupons programmatically using the [Import coupons][importCoupons] endpoint.
Alternatively, [import coupon codes][importingCodes] using the Campaign Manager.

:::

## Prerequisites

1. You have [created an Application](/docs/product/applications/create-and-manage-applications.md)
   and at least one [campaign](/docs/product/campaigns/create-and-manage-campaigns.md) in Talon.One. Make a note of
   their respective IDs.
1. You have created a [Management API key](/docs/product/account/dev-tools/manage-mapi-keys.md)
   that allows access to the [Import coupons][importCoupons] endpoint, and you've saved the
   generated API key.

## Step 1: Collect the existing coupon codes

From your legacy coupon or voucher system, export the existing coupon codes in any
format available, ideally as CSV.

This step depends on your legacy coupon system, which usually offers an API, a CSV export
functionality, or a way to export coupons directly from the database.

## Step 2: Generate a CSV file to import coupons

Talon.One requires your coupon data to be provided as a CSV file. The [Import coupons][importCoupons]
endpoint imports a given CSV file's data in a given campaign.

Use the following sample to create your CSV file of coupons to import. The sample contains
all supported columns. Only the `value` column is required.

```csv title="Coupon CSV structure"
"value","expirydate","startdate","recipientintegrationid","limitval","attributes"
xmas20,2020-12-30T01:00:00Z,2020-12-01T01:00:00Z,customer123,1,"{""Category"": ""10_off"", ""Event"": ""Christmas""}"
xmas19,2019-12-30T01:00:00Z,2019-12-01T01:00:00Z,customer456,1,"{""Category"": ""10_off"", ""Event"": ""Christmas""}"
xmas18,2018-12-30T01:00:00Z,2018-12-01T01:00:00Z,customer789,0,"{""Category"": ""20_off"", ""Event"": ""Christmas""}"
```

:::note
- In this example, we are setting two attributes to each coupons: `Category` and `Event`.
  These are examples of custom attributes. If you need custom attributes,
  [create them](/docs/dev/concepts/attributes.md) before the import.
- For detailed column descriptions, see [Import coupons][importCoupons].
:::

## Step 3: Import the coupons

Send a request to the [Import coupons][importCoupons] endpoint with your
generated CSV file as the payload. Assuming you have your CSV file saved in the same folder,
the curl request looks as follows:

```bash
curl https://example.talon.one/v1/applications/$YOUR_APP_ID/campaigns/$YOUR_CAMPAIGN_ID/import_coupons \
 -H "authorization: ManagementKey-v1 $YOUR_API_KEY" \
 -F "file=@/path/to/yourfile.csv"
```

More complex scenarios can require you to use multiple campaigns or even varying
attributes on individual coupons.

## Step 4: Mark coupon codes as redeemed

To mark imported coupons as redeemed, use the [Update customer session][updateCS]
endpoint and set the following data:

1. Make the session an anonymous session by setting the `profileId` property to an empty string.
1. Set the `state` property to `closed`. Learn more about [states](/docs/dev/concepts/entities/customer-sessions.md#customer-session-states).
1. Add the coupon code(s) to the session.

```json title="Marking coupons as redeemed"
{
  "customerSession": {
    "profileId": "",
    "state": "closed",
    "couponCodes": ["xmas20", "xmas19", "xmas18"],
  }
}
```

## Related pages

- [Create custom coupons](/docs/dev/tutorials/create-custom-coupons.md)
- [Import coupons via CSV file endpoint][importCoupons]
- [Importing coupon codes][importingCodes]

[importCoupons]: /management-api#tag/Coupons/operation/importCoupons
[updateCS]: /integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2
[importingCodes]: /docs/product/campaigns/coupons/manage-coupons.md#import-coupon-codes