# Create coupon on loyalty tier upgrade

> This tutorial describes how to trigger effects when a customer reaches a new loyalty tier.

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

To do so, we'll use the **Trigger Rule Engine: Tier upgrade** integration in the
[Integration Hub](/docs/dev/integration-hub/overview.md) to run a
[rule](/docs/product/rules/overview.md) after tier upgrades.

As an example, we'll create a welcome coupon for customers who reach the Gold tier. When a
tier upgrade happens, the integration sends a custom event to the Rule Engine, which then evaluates it
and creates a coupon for the new Gold tier member.

For more use cases, see the [overview of the integration](/docs/dev/integration-hub/available-integrations.md#trigger-rule-engine).

:::tip
The **Trigger Rule
Engine: Tier downgrade** integration works in a similar way, so you can also use this tutorial
to trigger effects when a customer moves to a lower tier.
:::

## Prerequisites

- You are an [admin](/docs/product/account/account-settings/manage-roles.md#admin-role)
  user.
- You have created an [Application](/docs/product/applications/create-and-manage-applications.md) and
  a [campaign](/docs/product/campaigns/create-and-manage-campaigns.md).
- You have set up a [profile-based loyalty
  program](/docs/product/loyalty-programs/profile-based/create-pb-programs.md) with at
  least two [tiers](/docs/product/loyalty-programs/profile-based/use-loyalty-tiers.md), so
  that a customer can change tier. For this tutorial, we assume the loyalty program has a
  Silver and a Gold tier.
- The loyalty program is [connected](/docs/product/loyalty-programs/manage-loyalty-programs.md#manage-general-program-settings)
  to your Application.

## Configure your Application

<StepsContainer>

### Create an Integration API key

In your Application, create an [Integration API
key](/docs/product/applications/manage-api-keys.md).

:::important
Ensure the Application is
[connected](/docs/product/loyalty-programs/manage-loyalty-programs.md#manage-general-program-settings)
to your loyalty program.
:::

### Create custom attributes

[Create three custom attributes](/docs/product/account/dev-tools/manage-attributes.md#create-a-custom-attribute)
to store the previous and current tier values, as well as the customer profile ID:

| Entity | Event type           | Type   | API name               |
| ------ | -------------------- | ------ | ---------------------- |
| Event  | `LoyaltyTierUpgrade` | String | `OldTier`              |
| Event  | `LoyaltyTierUpgrade` | String | `CurrentTier`          |
| Event  | `LoyaltyTierUpgrade` | String | `ProfileIntegrationID` |

:::tip
For a list of the available event attributes and their types, see the [overview of the
integration](/docs/dev/integration-hub/available-integrations.md#trigger-rule-engine).
:::

This automatically creates a [custom
event](/docs/dev/concepts/entities/events.md#custom-events) named
`LoyaltyTierUpgrade` that contains the three attributes.

### Create a rule

In your campaign, [create a rule](/docs/product/rules/create-and-manage-rules.md) to issue
a welcome coupon when a customer reaches the Gold tier:

| What           | Name                                               | Properties                                                                                                                                                                                                                                                                                                                        |
| -------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Conditions** | Check for event typesand custom event values | Event type: <code>LoyaltyTierUpgrade</code><Attribute name="OldTier (Event)" type="custom" /> is equal to <code>silver</code> And ...<Attribute name="CurrentTier (Event)" type="custom" /> is equal to <code>gold</code> |
| **Effects**    | Create coupon code                                 | Recipient: Current Customer (Friend)Code pattern > Use custom code pattern:Code length: <code>4</code>Prefix: <code>WELCOMEGOLD-</code>                                                |

</StepsContainer>

## Configure the integration

<StepsContainer>

### Create an instance

Create an [instance](/docs/dev/integration-hub/overview.md#integrations-instances-and-flows) in
the [Integration Hub](/docs/dev/integration-hub/overview.md):

1. Open <Account className="icon"/> > **Integrations** > **Generic integrations**.
1. Open the **Trigger Rule Engine: Tier upgrade** integration and click **Configure**.
   If instances already exist, click **Add instance**.
1. On the **Initial Configuration** page, enter a descriptive name for the instance, for
   example, `Trigger tier upgrade event`, and click **Next**.

### Configure the connection

On the **Connection** page, enter the following:

| Field        | Value                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------- |
| **Base URL** | The base URL of your Talon.One deployment.Example: `mycompany.europe-west1.talon.one` |
| **API key**  | The Integration API key you [created](#create-an-integration-api-key).                      |

### Select a loyalty program

On the **Loyalty Program** page, select the loyalty program connected to your Application.

The integration will only process tier upgrades from this loyalty program.

### Configure event mapping

On the **Event Configuration** page:

1. Click **Add to Field Mappings**.
1. In **Field Mappings**, map the tier upgrade notification fields to the custom
   attributes you [created](#create-custom-attributes). In this example, the source and
   target field names are the same, but you still must add them explicitly.
   `ProfileIntegrationID` is automatically mapped, you don't need to add it.

   | Source field name      | Target field name      |
   | ---------------------- | ---------------------- |
   | `OldTier`              | `OldTier`              |
   | `CurrentTier`          | `CurrentTier`          |

1. In **API Event Type**, enter `LoyaltyTierUpgrade`. This must match the event type you
   assigned to the [custom attributes](#create-custom-attributes).

</StepsContainer>

## Test the setup

Let's test our setup by triggering a loyalty tier change for a customer:

1. [Manually add loyalty
   points](/docs/product/loyalty-programs/profile-based/manage-pb-lp-data.md#manually-add-loyalty-points)
   to a customer's profile. Add enough points to trigger a tier change from Silver to
   Gold.
1. In your Application, open the <EventMenuIcon className="icon"/> [**Events** page](/docs/product/applications/display-events.md#list-events).
1. In the list of events, find the `LoyaltyTierUpgrade` event for the customer whose tier
   you just upgraded. If you don't see the event, wait a few minutes and refresh the page.
1. In the **Effects** column, click **1 triggered**.

The **Triggered effects** drawer opens, showing the coupon code created for the customer,
for example, `WELCOMEGOLD-Y88B`.