Skip to main content

Creating giveaway programs

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 date in RFC3339 by which the code be start being awarded.
  • enddate: The optional date in RFC3339 until which the code can be awarded.
  • attributes: The optional field used to update custom attributes. See Setting custom attributes.
important
  • The startdate and enddate properties have nothing to do with the validity of the code. They only indicate when the code can be awarded. The validity of a code is managed by the provider of the code.
  • You can use the time zone 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 and in the API docs.

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​

To import giveaway codes:

  1. On the leftmost menu, click Giveaways.

  2. In the top-right corner of the page, click Create Giveaway Pool.

  3. In Environment, select the environment where you want to create your giveaway pool.

    note

    You cannot change the environment after you create the giveaway pool.

  4. In Name, type a name for the pool.

  5. (Optional) In Description, enter some information to help you identify the pool.

  6. Click Upload a CSV File, browse to the CSV file you created earlier, and click Create Giveaway Pool.

The giveaway 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, we 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​

Awarding a giveaway triggers an effect, like any other rule effect.

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 or willAwardGiveaways, if some giveaway codes are awardable at the current date.

See the giveaway effect JSON structure.

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 three codes will be awarded to the customer.

The integration layer is responsible for processing the effect's data.