> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yorlet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Grant points with a workflow

> Award a custom loyalty programme when something happens in Yorlet or another system.

Use **Grant automatically** on the programme for **Rent on time**, **New lease**, **Move in**, **Renewal**, **Tenure milestone**, and **Birthday**. For **Custom**, **One time**, and **Referral** — or any occasion Yorlet does not grant for — create a [workflow](/business-automation/workflows/overview) that runs **Grant loyalty points**.

## Prerequisites

* [Loyalty](/loyalty) enabled, and a [programme](/loyalty/programs) to grant from. **Custom**, **One time**, and **Referral** have no **Grant automatically** switch.
* [Workflows](/business-automation/workflows/overview) enabled. **Grant loyalty points** only appears in **Add a step** when Loyalty is on.

<Warning>
  Do not add a workflow for an occasion that already has **Grant automatically** on, or customers can be rewarded twice.
</Warning>

## Create the programme

To create a programme to grant from a workflow, follow these steps:

1. Go to [Loyalty programmes](https://dashboard.yorlet.com/loyalty/programs).
2. Click **New programme**.
3. Set **Type** to **Custom**, **One time**, or **Referral**.
4. Set **Reward points**.
5. Click **Create**.

See [Programmes](/loyalty/programs) for every field.

## Create the workflow

To grant that programme from a workflow, follow these steps:

1. Go to the [Workflows page](https://dashboard.yorlet.com/workflows) and click **New workflow**.
2. Click **Workflow name** and enter a name, for example "Grant welcome points".
3. Select **Trigger** and choose a **Trigger type**. See [Triggers](/business-automation/workflows/triggers) and the recipes below.
4. Click **Add step**, open **Loyalty**, and choose **Grant loyalty points**.
5. Set **Loyalty programme** to the programme you created.
6. Set **Recipient type** to **Customer**. Set **Recipient** with **Insert variable**. This defaults to `{{ trigger.object.customer }}` when the trigger has a customer. Inside a **For each**, use `{{ loop.item.id }}`.
7. Leave **Points** blank to use the programme reward, unless this run should override it.
8. Click **Publish**.

Only **Active** workflows run. See [Create a workflow](/business-automation/workflows/create-a-workflow).

## Choose a trigger

| Trigger type                                  | When to use it                                                                                                                                                                                                                                                                                                                                                                                 |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Database event**                            | Something in Yorlet that is not already covered by **Grant automatically**. Pick an **Event** from the list, grouped by record. Examples: `contract.completed`, `maintenance.issue.created`, `application.accepted`. Do not use `invoice.paid`, `application.completed`, `tenancy.activated`, or `renewal_intent.completed` if a matching automatic programme exists.                          |
| **API request**                               | Another system should start the grant without calling the Loyalty API. Add **Input parameters** such as `customer` (String, required). Set **Recipient** to `{{ trigger.input.customer }}`. Developers trigger the workflow with `POST /v1/workflows/:id/trigger`. If they already have a secret key, they can [POST program events](/development/integrations/loyalty/grant-rewards) instead. |
| **Tenancy milestone** or **Invoice past due** | You need extra steps as well as points, for example a task. Prefer **Grant automatically** on a **Tenure milestone** programme when points are the only action.                                                                                                                                                                                                                                |

## Grant every customer on a tenancy or application

If the trigger has a list of customers, add **For each** after the trigger:

1. Set **Array** to `{{ trigger.object.customers }}`.
2. On the **Each item** branch, add **Grant loyalty points**.
3. Set **Recipient** to `{{ loop.item.id }}`.

A loop can run for at most 50 items. See [Conditions and loops](/business-automation/workflows/conditions-and-loops).

## Only grant for some records

Add **If / else** after the trigger if you only want the workflow to continue for some records — for example an amount threshold, a building, or an application type. See [Conditions and loops](/business-automation/workflows/conditions-and-loops).

## Check it ran

Open the workflow and look at **Recent runs**. Failed grants — for example no matching resident, or an archived programme — show on the run. See [Runs](/business-automation/workflows/runs).

## Custom programme when a contract is completed

To grant a custom programme when a contract is completed, follow these steps:

1. Create a **Custom** programme with the points you want to award.
2. Create a workflow named, for example, "Grant points when a contract is completed".
3. Set **Trigger type** to **Database event** and **Event** to `contract.completed`.
4. Add **Grant loyalty points**. Set **Loyalty programme** to that programme, **Recipient type** to **Customer**, and **Recipient** to `{{ trigger.object.customer }}`.
5. Click **Publish**.

## Points for every customer on a tenancy

To grant points to every customer on a tenancy, follow these steps:

1. Create a **Custom** programme.
2. Create a workflow with a **Database event** trigger that has `customers` on the record — for example `tenancy.activated`, but only if you do not also have **Grant automatically** on a **Move in** programme.
3. Add **For each** with **Array** `{{ trigger.object.customers }}`.
4. On the **Each item** branch, add **Grant loyalty points** with **Recipient** `{{ loop.item.id }}`.
5. Click **Publish**.

## Grant from another system

To let another system start the grant from the Dashboard, follow these steps:

1. Create a **Custom** programme.
2. Create a workflow and set **Trigger type** to **API request**.
3. Click **Add** under **Input parameters**. Set the key to `customer`, the type to **String**, and turn on **Required**.
4. Add **Grant loyalty points**. Set **Recipient type** to **Customer** and **Recipient** to `{{ trigger.input.customer }}`.
5. Click **Publish**.

Your systems then call `POST /v1/workflows/:id/trigger` with `{ "input": { "customer": "cus_..." } }`.

If you already call Yorlet from a server with a secret key, you can POST `/v1/loyalty/program_events` instead. See [Grant loyalty rewards from your systems](/development/integrations/loyalty/grant-rewards).

Treat **Referral** like **Custom**: you choose the recipient. Yorlet does not record who referred whom.