# Coupons

> Discount codes as a percentage or a fixed amount, for the first charge, forever or for N months, with a validity period, a usage limit and applicable products. How the discount works at checkout and on renewals, and the messages buyers can see.

A **coupon** is a code buyers type at payment to get a discount: **LANCAMENTO20**, **BEMVINDO10**, **ALUNO2026**. It's for launches, partnerships, campaigns, and winning back people who gave up.

## What it's for

| Community | Coupon | What it does |
|---|---|---|
| Online school | `LANCAMENTO20` | 20% off the first monthly payment of the Student plan, up to 100 uses |
| Coworking space | `PARCEIRO30` | US$ 30 off a month for the first 3 months of the Resident plan, for the partner only |
| SaaS | `ANUAL10` | 10% off forever, on annual options only |
| Event | `GRUPO15` | 15% off the ticket, valid until the day before |

## How it works

### Types

| Type | Discount | Example |
|---|---|---|
| **Percentage** | A percentage of the amount | 20% of US$ 25 = US$ 5.00 |
| **Fixed Amount** | An amount in reais, per order | US$ 30 off |
| **Free Trial** | Extra trial days | +7 trial days |

### Duration (for subscriptions)

| Duration | On screen | The discount applies |
|---|---|---|
| **once** | *Discount applied only on first payment* | Only on the first charge |
| **forever** | *Discount applied on all payments* | On every charge, renewals included |
| **repeating** | *Discount applied for N months* | On the first N charges |

On a product sold once, the duration makes no difference: there's only one charge.

### Limits

| Field | What it's for |
|---|---|
| **Start Date** \* | When the code starts being valid |
| **End Date** | Until when. Left blank, it doesn't expire |
| **Maximum Uses** | How many times the code can be used in total. Left blank, unlimited |
| **Maximum per User** | How many times the same person can use it |
| **Applicable Products** | Which products and options it applies to. Empty: all of them |

Through the API, a coupon also takes: a minimum order amount, a maximum discount, first purchase in the community only, subscriptions only, one-time products only, excluded products, and whether it can be combined with another coupon.

### How the discount works at payment

1. At checkout, the buyer clicks **I have a coupon**, types the code and clicks **Apply**. The screen shows *"Coupon LANCAMENTO20 applied · −US$ 5.00"* and the duration (*"Discount on the first charge only."*).
2. The discount is calculated **before the fee**: the platform fee applies to the amount after the discount.
3. On an order with a plan and add-ons, a **fixed-amount** coupon is taken **once off the order**, split across the items in proportion to each one's amount; a **percentage** applies equally to each item it covers.
4. No item can go below **US$ 1.00** after the discount, unless the coupon brings the total to zero (see [100% coupon](#100-coupon)).
5. The use is recorded **when the payment is confirmed**. An open order (an unpaid boleto, for example) holds a use for up to 7 days.
6. On renewals, **forever** and **repeating** coupons keep applying for the agreed time.
7. With a [downsell](/monetizacao/downsell), the downsell discount comes first, then the coupon's.

### 100% coupon

A coupon that brings the total to zero becomes a **free purchase**: the buyer clicks **Get it free**, with no payment method and no card details, and gets access at once. There is no charge, no fee and no entry in the statement; the coupon use is recorded right away, once per buyer and product.

| Where | What happens |
|---|---|
| **One-off product**, no add-ons | Free purchase, with any duration |
| **Plan** (option with no trial period, no add-ons), **forever** coupon | Free purchase, and renewals charge nothing while the coupon covers them |
| **Plan**, **once** or **repeating** coupon | Refused: *"This coupon only zeroes the plan's first months; use a card to subscribe"*. A free purchase saves no card, so the next charge would have nothing to charge |
| **Installments** | Not covered by this rule |

It works the same for a person and for a [company](/membros/empresas#the-company-subscribes-and-pays): the company admin buys through the company checkout with the coupon, and the confirmation says *"Purchased for {company}"*. A total between US$ 0.00 and US$ 1.00 is still refused. See [Free product](/monetizacao/produtos#free-product).

The **Free Trial** type isn't accepted at payment (*"This type of coupon cannot be used at checkout"*).

### Status

The list shows each coupon with its uses, validity and status:

| Status | Meaning |
|---|---|
| **Active** | Valid |
| **Inactive** | Paused by you |
| **Expired** | Past the end date |
| **Exhausted** | Reached the maximum uses |

Above the list, **Search coupons** and the **Status** filter (**Active** or **Inactive**), in a button with a menu; the chosen filter becomes a chip with **×** and stays in the page address.

### Who can

Create, edit, pause and delete: **owner** and **admin**. **Finance** sees the coupons and their usage history.

## Step by step: create a coupon

*Role: owner or admin.*

1. **Monetization › Coupons › Create Coupon**.
2. **Code** \*: what the customer types (e.g. `LANCAMENTO20`). Unique within the community.
3. **Name** \*: for the staff (e.g. *March launch — 20%*).
4. **Type** \* and **Discount Value** \*.
5. **Duration** \*: once, forever or repeating (with the **Months**).
6. **Start Date** \* and, if you want, **End Date**.
7. **Maximum Uses** and **Maximum per User**, if you want to limit it.
8. Under **Applicable Products**, tick where it applies, or leave it empty to apply everywhere.
9. **Create**.

![Create Coupon](/screens/cupom-novo.png "Code, name, type, amount, duration, validity, limits and applicable products (interface in Portuguese).")

To pause it, change the status to **Inactive**. Deleting a coupon that has been used affects reports: the screen tells you how many times it was used.

## Examples with numbers

The platform fee is 6.99% + US$ 1.00 on the amount charged, after the discount.

**`LANCAMENTO20`: 20% once, on Growth Monthly (US$ 25).**
First monthly payment: US$ 25.00 − US$ 5.00 = **US$ 20.00**. Fee: US$ 1.40 + US$ 1.00 = US$ 2.40. The community keeps US$ 17.60. From the second payment on, US$ 25.00.

**`ANUAL10`: 10% forever, on Student Monthly (US$ 15).**
Every month: **US$ 13.50**. Fee: US$ 0.94 + US$ 1.00 = US$ 1.94. The community keeps US$ 11.56 a month, for as long as the subscription lasts.

**`PARCEIRO30`: US$ 30 repeating for 3 months, on Resident (US$ 300).**
Months 1 to 3: **US$ 270.00**. From month 4 on: US$ 300.00.

**A US$ 10 fixed amount on a plan + add-on order (US$ 25 + US$ 79 = US$ 104).**
The discount is US$ 10 on the order, split proportionally: US$ 2.40 on the plan and US$ 7.60 on the add-on. Total: **US$ 94.00**.

**A US$ 14.50 fixed amount on a US$ 15 plan.**
Refused: the item would cost US$ 0.50, below US$ 1.00.

**`FREE100`: 100% forever, on a US$ 15 monthly plan.**
The buyer clicks **Get it free** and is in at once. No monthly charge while the coupon applies, and no fee. The same coupon with a **once** duration is refused at checkout.

## Good practices

- **One code per campaign.** `INSTAGRAM20` and `NEWSLETTER20` with the same discount show where each sale came from, in the **Uses** column.
- **Always set an end date** on campaigns: a forgotten coupon becomes a permanent discount.
- **Maximum Uses** on partnerships, so a leaked code doesn't become the rule.
- **Prefer "once" or "repeating"** to "forever": "forever" reduces every renewal for as long as the person stays.
- **Test before you promote it**: apply the code at checkout with a member account and check the total.

## Messages buyers can see

| Message | Why |
|---|---|
| *Invalid coupon code* | The code doesn't exist |
| *Coupon has expired* | Past the end date |
| *Coupon is not yet valid* | Before the start date |
| *This coupon is not active* | It's paused |
| *Coupon usage limit has been reached* | Exhausted |
| *You have already used this coupon as many times as allowed* | Maximum per user |
| *This coupon does not apply to this product* | The product isn't among the applicable ones |
| *This coupon applies to orders of US$ X or more* | Minimum amount |
| *This coupon is only valid for your first purchase in this community* | First-purchase restriction |
| *With this coupon an item would cost less than US$ 1.00, the least that can be charged* | The discount is larger than the price |
| *This coupon only zeroes the plan's first months; use a card to subscribe* | A **once** or **repeating** 100% coupon on a plan |
| *Too many invalid coupon codes. Try again in a few minutes.* | 10 codes refused within 15 minutes |
| *The coupon is no longer valid and was removed. Nothing was charged; check the new total and try again.* | The coupon expired or ran out between applying it and paying |

## Common errors when creating

| Message | What to do |
|---|---|
| *A coupon with this code already exists in this community* | Use another code |
| *Enter how many months the repeating coupon lasts* | With **repeating**, fill in the **Months** |
| *Extra trial days only apply to free trial coupons* | Remove the extra days, or change the type |

## Frequently asked questions

**Does the coupon apply on renewal?**
**Forever** and **repeating** coupons do, for the agreed time. **Once** coupons apply only to the first charge.

**Can I give a plan away for free with a coupon?**
Yes, with a 100% **forever** coupon: the purchase closes with no payment and renewals charge nothing. With **once** or **repeating**, checkout refuses it. See [100% coupon](#100-coupon).

**Can two coupons be used?**
Only if both can be combined. By default, one coupon per order.

**Does the coupon reduce the platform fee?**
The fee is calculated on the discounted amount: a lower price also means a lower fee in reais.

**Can a member use a coupon when adding an extension later, from the Billing page?**
Not for now; coupons apply when buying the plan and on the last-chance offer.

**How do I know how many times a coupon was used?**
In the **Uses** column of the list, and in the coupon's usage history.

## In the API

`POST /api/coupons`, `PUT .../coupons/{id}`, `PATCH .../coupons/{id}/status`, `GET .../coupons/{id}/usage` and `POST .../coupons/validate` (`code`, `productId`, `amount`). At checkout, `couponCode` in `POST /api/checkout/calculate-price` and in `POST /api/checkout`; with a coupon that brings the total to zero, the response carries `free: true` (and `companyId` on a company purchase), and a 100% **once** or **repeating** coupon on a plan answers `400`. See [Coupons](/api/referencia/coupons).

## Related

- [Downsell](/monetizacao/downsell)
- [Checkout](/pagamentos/checkout)
- [Platform fee](/pagamentos/taxa-da-plataforma)