# Create giveaway programs

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

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

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 homogeneous. For example, you can create a pool that only contains
€10 Amazon gift card codes and another one for €20 Amazon gift card codes.

## Overview

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.

## Create a giveaway pool

### Define 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][RFC3339] by which the code be start being awarded.
- `enddate`: The optional date in [RFC3339][RFC3339] until which the code can be awarded.
- `attributes`: The optional field used to update custom attributes.
  See [Set custom attributes](#set-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:

```csv
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][createGiveaway].
:::

We can now import the file or customize it further.

#### Set custom attributes

If you have created [custom attributes](/docs/dev/concepts/attributes.md) 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:

```json
{
  "provider": "Amazon"
}
```

To insert it in the CSV file:

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

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

```csv
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""}"
```

### Import the CSV file

To import giveaway codes:

1. On the leftmost menu, click <Giveaways className="icon"/> **Giveaways**.
1. In the top-right corner of the page, click <Add className="icon"/> **Create Giveaway Pool**.
1. In **Environment**, select the [environment where you want to create your
   giveaway pool](/docs/product/giveaways/overview/#giveaway-pool-environments).

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

1. In **Name**, type a name for the pool.
1. (Optional) In **Description**, enter some information to help you identify the pool.
1. Click <Upload className="icon"/> **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][createGiveaway] endpoint.

### Award a giveaway

To award a giveaway, we use the **Award giveaway**
[rule effect](/docs/product/rules/effects/use-effects.md#award-a-giveaway).
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.

## Process 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](/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) 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][giveaway effect].

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.

## Related pages

- [Integrating Talon.One][integ]
- [Giveaways entity](/docs/dev/concepts/entities/giveaways.md)
- [Giveaway effect structure][giveaway effect]

[RFC3339]: https://www.ietf.org/rfc/rfc3339.txt
[integ]: /docs/dev/tutorials/integrate-talon-one.md
[createGiveaway]: /management-api#tag/Giveaways/operation/importPoolGiveaways
[giveaway effect]: /docs/dev/integration-api/api-effects.md#giveaways