# Create a custom effect to award minutes

> Talon.One offers a set of effects via its Integration API that you can use to get data to the integration layer. But sometimes, the [data that they return][effects] might not be what you require.

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

In this case, a [custom effect][managecustom] allows you to communicate any data from
Talon.One to the integration layer in the form of a structured effect.

Like any other effect, custom effects are returned when you call
the [Update customer session](/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
when a rule is valid.

:::note

- This tutorial assumes you have a basic understanding of
  [effects][effects],
  [attributes][attributes] and
  [rules](/docs/product/rules/overview.md).
- If you do not want to return the data as an effect, you can use
  a [webhook](/docs/product/account/dev-tools/manage-webhooks.md) instead.

:::

## Overview

Let's imagine we run a company that rents bicycles by the minute and we want to reward
customers with free minutes when they use a coupon code.

To do this, we must create a rule with the following logic:

- If the coupon is valid then send the awarded number of minutes to the integration
  layer.

No [core effects][effects] provides information about awarded minutes, so let's
create a custom effect to cover our use-case.

## Create a custom effect

Let's create our **Award minutes** custom effect. It will appear in the Rule Builder as a
new effect type.

1. In the bottom-left of the Campaign Manager, click <Account className="icon"/> **Account** > <Tools className="icon"/> **Tools** > **Custom Effects**.
1. Click **Create Custom Effect**.
1. In **Scope**, select **Cart (Session)**.
1. In **API name**, type `Award_minutes`.
1. In **Rule Builder name**, type `Award minutes`
   is the name of the effect. It appears in the effects section when we create a rule.
1. In **Applications**, select your Application.

Let's add parameters to our effect.

### Add parameters

Parameters represent the data of the effect that can be edited from the
Rule Builder's UI.

In our case, we need a number of minutes and the ID of the customer involved.
To do this we only need one parameter because:

- The number of minutes should be customizable from the Campaign Manager's
  Rule Builder.
- The profile ID is set by the integration layer without user input when we
  create [sessions](/docs/dev/concepts/entities/customer-sessions.md) so we do not need
  a parameter.

Let's create the parameter:

1. In **Param type**, select **number**.
1. In **Param name**, let's type a user-friendly name such as `minutes`.
   This will appear in the Rule Builder.
1. In **Param Description**, let's type `The number of minutes awarded.`.
   This will appear in the Rule Builder.

### Create the payload

We've defined the parameter for the users of the Rule Builder, now
let's define the payload for our integration layer.

We want the effect to contain:

- The number of minutes defined with a parameter.
- The profile ID represented by the profile's `IntegrationId` built-in
  [attribute][attributes].

To do this, we use the following payload:

```json
{
  "awardedMinutes": "${$minutes}",
  "customerID": "${$Profile.IntegrationId}"
}
```

Click `Create` and our effect is ready for use.

## Create a rule

In a [standard campaign](/docs/product/campaigns/overview#standard-campaigns), let's
create the rule to award minutes.

1. Open the Rule Builder in your campaign and create a rule:
   1. Condition: **Coupon code is valid**
   1. Effect: **Award minutes**
1. Edit the value of the **minutes** parameter.
1. Save and enable the Campaign.

When the rule triggers, the integration layer receives the following example payload:

```json {17-28} title="Update customer session response"
{
    "createdCoupons": [],
    "createdReferrals": [],
    "effects": [
        {
            "campaignId": 3882,
            "rulesetId": 12230,
            "ruleIndex": 0,
            "ruleName": "Award minutes",
            "effectType": "acceptCoupon",
            "triggeredByCoupon": 3308130,
            "props": {
                "value": "SUMMER-2021"
            }
        },
        {
            "campaignId": 3882,
            "rulesetId": 12230,
            "effectType": "customEffect",
            "triggeredByCoupon": 3308130,
            "props": {
                "effectId": 1,
                "name": "Award minutes",
                "payload": {
                    "awardedMinutes": "30",
                    "ProfileId": "111"
                }
            }
        }
    ],
    "ruleFailureReasons": [],
    "triggeredCampaigns": [
        {
           ...
        }
    ]
}
```

We can now parse the response to extract the data we needed. Notice we get two effects, the
usual core `acceptCoupon` effect when a coupon is valid and a `customEffect` with the data
we need: the awarded minutes and the customer ID.

## Related pages

- [Manage custom effects][managecustom]
- [Integration Talon.One tutorial](/docs/dev/tutorials/integrate-talon-one.md)
- [API effects][effects]
- [Create a webhook](/docs/dev/tutorials/create-a-webhook.md)

[attributes]: /docs/dev/concepts/attributes.md
[effects]: /docs/dev/integration-api/api-effects.md
[managecustom]: /docs/product/account/dev-tools/manage-custom-effects.md