Import Existing Coupons

If you are replacing an exising coupon or voucher system with Talon.One, you may need to transfer coupon codes from the old system to ensure that these codes continue to work. This guide shows how you can use the coupon import endpoint from our Management API to create coupons programmatically.

#Collect the existing coupon codes

How you do this is dependent on the legacy voucher system. There may be an API, or a CSV export functionality, or you may need to dump coupons directly from the application database.

#Create a campaign

Before creating coupons in Talon.One, you need to create one or more campaigns that define coupon validation conditions and coupon effects. As a general rule, you will use one campaign for each kind of validation you need to support. E.g. if one set of coupons is only valid for orders with a total value greater than $50, and another set is valid for customers in a certain geographic region, these should belong to 2 different campaigns.

Once the campaign has been created, make a note of its ID for later use in our API calls.

#Generate a CSV file that has the correct structure (1 file per Talon.One campaign)

Once you've collected the raw coupon data from your legacy system and you know the ID of the campaign you want to import the codes into, you will have to transform your raw data into a csv file with all the necessary data.

The structure of a coupon import CSV file is very similar to our own exportCoupons CSV files (using ISO8601 for dates). Below is an example showing a csv file with all available columns provided:

"value","expirydate","startdate","recipientintegrationid","limitval","attributes"
COUP1,2018-07-01T04:00:00Z,2018-05-01T04:00:00Z,cust123,1,"{""Category"": ""10_off"", ""Month"": ""May""}"
COUP_2,2018-07-01T04:00:00Z,2018-05-01T04:00:00Z,cust456,1,"{""Category"": ""10_off"", ""Month"": ""May""}"
PROMO,2018-07-01T04:00:00Z,2018-05-01T04:00:00Z,cust000,0,"{""Category"": ""20_off"", ""Month"": ""May""}"
PROMO2,2018-07-01T04:00:00Z,2018-05-01T04:00:00Z,,20,"{""Category"": ""20_off"", ""Month"": ""July""}"

Note that of these columns, only the value column is required. All others are optional. Limits default to 1 if they are not provided.

#Get a session token

The first step when using the Management API is to create a new session token. See our Authentication reference for more details on how to obtain a session token.

#Perform a importCoupon API call with the csv file as the payload

Now you have all the pieces you need to import your coupons into Talon.One. The generalized process is to perform the importCoupons operation, with your generated csv file as the payload. Assuming you have your csv file saved in the same folder, you could import the coupons by executing a simple curl command such as the following one:

curl https://example.talon.one/v1/applications/42/campaigns/3/import_coupons \
 -H "authorization: Bearer $YOUR_TOKEN" \
 -F "file=@/path/to/yourfile.csv"

#Conclusion

This article has outlined the general process for importing existing coupon codes into Talon.One, and demonstrated the simplest case with a curl command. More complex scenarios may need to use multiple campaigns or even varying attributes on individual coupons. To see more of what's possible with coupon attributes check out our tutorial on creating custom coupons with the API.