Skip to main content

Creating giveaways

Giveaways are account-level entities that can be shared among the Applications of your choice.

A giveaway program relies on pools which contain all the single-use codes to be given to your customers via rule effects. A giveaway pool should contain codes that are related and homogenous. For example, you can create a pool that only contains €10 Amazon gift card codes and another one for €20 Amazon gift card codes.

Understanding the context#

In our case, let's imagine we want to offer an Amazon gift card to any customer that completes an order of more than €1000.

To do this, let's create a giveaway pool that will contain our Amazon gift card numbers and a rule that will check the order amount and trigger the giveaway appropriately.

Creating a giveaway pool#

Defining the CSV file#

A pool is a list of giveaway items. To create a pool in Talon.One, we must define our pool as a CSV file. Each item of the list contains the following properties:

  • code: the code of your giveaway, for instance, a gift card redemption code.
  • startdate: the optional start date in RFC3339 of the code redemption period.
  • enddate: the optional last date in RFC3339 of the code redemption period.
  • attributes: the optional field used to update custom attributes. See below.
important
  • The startdate and enddate have nothing to do with the validity of the codes. They are only used by the Rule Engine to award the codes or not.
  • You can use the timezone of your choice. It is converted to UTC internally by Talon.One.

Let's imagine we have created the following CSV file:

code,startdate,enddate
2395-b2s-328tks,2021-01-10T23:00:00Z,2021-06-11T23:00:00Z
8476-57v-33a787,2021-01-10T23:00:00Z,2021-06-11T23:00:00Z
3676-09r-42a179,2021-01-10T23:00:00Z,2021-06-11T23:00:00Z
note

You can find a sample CSV in the Create giveaway pool view in the Campaign Manager.

We can now import the file or customize it further.

Setting custom attributes#

If you have created custom attributes for your giveaways, you can set these attributes in the CSV file as well.

To do so, add an attributes column. This field contains a JSON object of key-value pairs representing the attributes and their respective value.

For example, let's imagine we have created a custom attributes called provider. We want to set this attribute to the name of the company that we obtained each code from: Amazon.

We can use the following JSON to update the code:

{
"provider": "Amazon"
}

To insert it in the CSV file:

  1. Double the double-quotes in the JSON.
  2. Wrap the whole object in double-quotes.

We get "{""provider"": ""Amazon""}" that we add to our CSV file:

code,startdate,enddate,attributes
2395-b2s-328tks,2021-01-10T23:00:00Z,2021-06-11T23:00:00Z,"{""provider"": ""Amazon""}"
8476-57v-33a787,2021-01-10T23:00:00Z,2021-06-11T23:00:00Z,"{""provider"": ""Amazon""}"
3676-09r-42a179,2021-01-10T23:00:00Z,2021-06-11T23:00:00Z,"{""provider"": ""Amazon""}"

Importing the CSV file#

We can import our CSV file via the Campaign Manager:

  1. In the left sidebar, click Giveaways and click Create giveaway pool.
  2. Type a name in the Name field, and select the applications that should get access to this pool.
  3. Click Upload a CSV file and browse to the CSV created earlier and click Save.

The pool is created and we can start using its content in our campaigns.

Alternatively, we can use the Import giveaways codes endpoint.

Awarding a giveaway#

To award a giveaway, let's use the Award giveaway rule effect. When we select this effect, we can choose the pool and the recipient of the award.

In our case, we can decide that the effect should be applied when the customer has purchased EUR500 worth of items.

Processing the effect#

As for every effect, the Integration API tells us when an effect was applied. For more background on how to manage sessions, see Integrating Talon.One.

In this case, when the effect is triggered, the Update Customer Session endpoint returns the effects array that contains an item whose effectType property is awardedGiveaways.

The main properties of a giveaway are startDate, endDate and code, which help the integration layer decide what to do with the giveaway.

In our case, if the current date is between 1st Oct 2021 and 6th Nov 2021, which is the date we defined in the CSV for our codes, one of the 3 codes will be awarded to the customer.

See also: