# Award loyalty points after delivery

> You can reward customers with loyalty points after their order is delivered by using advanced events and a connected session ID to reference the original purchase.

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

Let's imagine we run an ecommerce store and want to give customers 10% of their session
total as loyalty points after their shipment arrives. For example, a $300 order earns 30
points. Our order management system (OMS) notifies Talon.One when the delivery is confirmed.

## Overview

This use case requires [advanced events](/docs/dev/concepts/entities/events.md#advanced-events),
since the delivery confirmation arrives after the purchase session is already closed. Only
advanced events can reference a closed session's data, via the connected session ID.

The flow works as follows:

1. A customer completes an order. Your integration closes the [customer
   session](/docs/dev/concepts/entities/customer-sessions.md#customer-session-states) in
   Talon.One.
1. You ship the order, and your order management system tracks the shipment.
1. When the order is delivered, the OMS calls the [Track advanced
   event](/integration-api#tag/Events/operation/trackEventV3) endpoint, using the closed
   customer session as the [connected
   session](/docs/dev/concepts/entities/events.md#advanced-events).
1. The [Rule Engine](/docs/product/rules/overview.md) evaluates the event, reads the total of the connected session, and
   awards loyalty points.

## Prerequisites

- You have created an [Application](/docs/product/applications/overview.md) and a [campaign](/docs/product/campaigns/overview.md)
  in Talon.One.
- You have set up a [profile-based loyalty
  program](/docs/product/loyalty-programs/profile-based/create-pb-programs.md). The
  loyalty program is connected to your Application.
- The [**Loyalty** feature](/docs/product/campaigns/settings/manage-campaign-features.md)
  is enabled in your campaign.
- Your Application contains at least one [closed session](/docs/dev/concepts/entities/customer-sessions.md).

## Set up the integration

<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 the event

For this tutorial, we assume your order management system sends an event of type
`orderStatusChanged` and the delivery status in a `deliveryStatus` property.

To allow Talon.One to process this event, create an [advanced
event](/docs/dev/concepts/entities/events.md#advanced-events) and a [custom
attribute](/docs/product/account/dev-tools/manage-attributes.md):

1. Click <Account className="icon"/> > <Tools className="icon"/> **Tools** >
   **Attributes** > **Create Attribute**.
1. In **Entity**, select **Event**.
1. In **Event type**, enter `orderStatusChanged`.
1. In **Type**, select **String**.
1. In **API name**, enter `deliveryStatus`.
1. In **Name**, enter `Delivery Status`.
1. In **Description**, enter `The status of the delivery`.
1. Click **Create Attribute**.

### Create a promotion rule

Open your campaign and [create a promotion
rule](/docs/product/rules/create-and-manage-rules.md#create-a-promotion-rule) to award
points when the delivery event is received.

The rule checks for the `orderStatusChanged` event type and the delivery status, and awards
points based on the total of the connected session.

| What           | Name                                               | Properties                                                                                                                                                                                                                              |
| -------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Conditions** | Check for event typesand custom event values | Event type: <code>orderStatusChanged</code><Attribute name="Delivery Status (Event)" type="custom" /> is equal to <code>delivered</code>                                     |
| **Effects**    | Add loyalty points                                 | **Loyalty program**: Select your loyalty program.**Recipient**: `Current Customer (Friend)`**Reason**: `Delivery reward`**Amount of points**: `[AdvancedEvent.ConnectedSession.Total]*10%` |

### Trigger the event

In your OMS, implement the logic to call the [Track advanced
event](/integration-api#tag/Events/operation/trackEventV3) endpoint when the OMS confirms
delivery. Include the `connectedSessionId` parameter to link the event to the original
purchase session.

To send a test event, use the following cURL command, where:

- `YOUR_DEPLOYMENT_URL` is the base URL of your Talon.One deployment, for example,
  `mycompany.europe-west1.talon.one`.
- `YOUR_API_KEY` is the Integration API key you [created](#create-an-integration-api-key).
- `CUSTOMER_PROFILE_ID` is the ID of an existing customer profile.
- `EVENT_INTEGRATION_ID` is a unique identifier for this event, for example, `testevent1234`.
- `CLOSED_SESSION_ID` is the ID of an existing closed customer session.

```bash
curl https://YOUR_DEPLOYMENT_URL/v3/events \
  -X POST \
  -H "Authorization: ApiKey-v1 YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "CUSTOMER_PROFILE_ID",
    "integrationId": "EVENT_INTEGRATION_ID",
    "type": "orderStatusChanged",
    "connectedSessionId": "CLOSED_SESSION_ID",
    "attributes": {
      "deliveryStatus": "delivered"
    }
  }'
```

:::note
- The session must be in the `closed` state. If the session is still open, Talon.One returns
  a `400` error.
- Advanced events are idempotent. If you send the same event more than once with the same
  ID, Talon.One returns a `409` error.
:::

### Verify the result

After the call, Talon.One evaluates the rule and awards loyalty points to the customer
profile.

You can verify this in two ways:

- In your Application, on the <Customers className="icon" /> **Customers** page, open the
  customer profile and check the [**Loyalty
  Points**](/docs/product/applications/display-customer-profiles.md#loyalty-points) tab.
- Use the [Get customer's loyalty
  balances](/integration-api#tag/Loyalty/operation/getLoyaltyBalances) API endpoint.

The advanced event call is also listed in the
[Events](/docs/product/applications/display-events.md) page of your Application.

</StepsContainer>

## Related pages

- [Event entity](/docs/dev/concepts/entities/events.md)
- [Create a point-based loyalty campaign](/docs/product/tutorials/loyalty/loyalty-points-program.md)
- [Customer sessions](/docs/dev/concepts/entities/customer-sessions.md)