# Promoters

A promoter program lets people sell for you and earn from it: a street team, an influencer, a church usher or a club promoter. Each one gets a link or code to share, every sale is tied to the person who brought it, and you pay them a commission.

Promoter accounts, promoter links, tracked sales and commission payouts are not offered in the API today. They are listed on [what's coming](https://docs.vabu.live/whats-coming.md). What you can use now is the coupon code on an event. You can hand one code to each promoter and count how often it was used.

## How the pieces fit

| Piece | What it is | Offered today |
|---|---|---|
| Promoter | A person who sells for you. | No |
| Link or code | What the promoter shares with buyers. | Event coupon codes |
| Tracked sale | A sale tied to the promoter who brought it. | No |
| Commission | What the promoter earns on each sale. | No |
| Payout | Paying the commission out. | No |

## Use a coupon code per promoter

A coupon is a code for one event. An organizer sets its discount as a percentage, a fixed amount or a set price. A coupon can also have a minimum spend, a cap on the discount, a limit per buyer, a total number of uses, a start and end date, and a list of ticket types it applies to. A code is unique within an event and is case sensitive.

To give each promoter a code:

1. Create one coupon per promoter on the event, for example `AMINA10`.
2. Give the code to the promoter to share.
3. Your app checks a code at checkout with the calls below, and sends it as `coupon_code` when it creates the order.
4. Read the coupon list to see how often each code was used. Each coupon shows `redeemed_count` and an `analytics` block with `redeemed_count`, `orders_count` and `total_discount`.

This counts how many times a code was used and how much discount it gave. It does not link the sale to a promoter account or work out a commission, so you pay promoters yourself. Coupons can be created, changed or deleted until the event starts.

## What you can call today

| Method | Path | What it does |
|---|---|---|
| GET, POST | `/v1/organizer/events/{event}/coupons` | List coupons with redemption counts, or create one. |
| PUT, DELETE | `/v1/organizer/events/{event}/coupons/{coupon}` | Update or delete a coupon. |
| POST | `/v1/coupons/validate` | Check a code for an event. Returns its type and value. No sign-in. |
| GET | `/v1/events/{event}/coupon/availability` | Check that a code works for a ticket type. No sign-in. |
| GET | `/v1/events/{event}/coupon/discount` | Get the discount a code gives for a ticket type and quantity. No sign-in. |

The full parameters for each call are in the [API reference](https://docs.vabu.live/api.md).

## Calling these endpoints

The three buyer checks take only `X-Tenant-Code`, with no sign-in. The organizer coupon routes take a signed-in user token (`Authorization: Bearer ...`, a Vabu ID or Payd ID token) plus `X-Tenant-Code`, in live mode, and accept an optional `X-Organization-Id` header to pick which organization you act for. Creating or changing coupons needs the Owner, Admin or Editor role in the organization. Test keys and publishable keys are refused on these routes today. See [which credentials each endpoint takes](https://docs.vabu.live/concepts/keys-and-scopes.md#which-credentials-each-endpoint-takes).

## Events you can subscribe to

| Event | When it fires |
|---|---|
| `events.order.paid` | An event order is fully paid. It has a `promoter_id` field, which is empty today because orders do not record a promoter yet. |

See [events](https://docs.vabu.live/events/index.md) for the full payload and [webhooks](https://docs.vabu.live/concepts/webhooks.md) for delivery and signatures.

## Related

- [Events and ticketing](https://docs.vabu.live/products/events.md) for events, ticket types and orders.
- [Payments](https://docs.vabu.live/products/payments.md) for how a coupon order is paid.
- [What's coming](https://docs.vabu.live/whats-coming.md) for promoter links, tracked sales and commissions.