# Vouchers and Discounts

## Overview

You can use vouchers to apply discounts to new subscriptions. The voucher needs to be created beforehand and can be applied to one or more subscriptions that need the same discount.

Vouchers can be configured to discount the first invoice, every invoice, or all invoices created within a certain time window by configuring their recurrence.

When a voucher is applied to a subscription, the resulting discount will be available in the subscription billing details.

In order to use vouchers, [billing users](/docs/billing/billing-users) has to be enabled.

## Validity

Once a voucher is created, it can be used as a blueprint that applies the specified discount to all invoices for a subscription.

### Recurrence types

| Type | Behavior |
|---|---|
| `once` | Applied to the **first invoice only**, regardless of when it is created. |
| `repeating` | Applied to **every invoice created within a time window** of `durationInMonths` months from when the discount was attached to the subscription. |
| `forever` | Applied to every invoice for the lifetime of the subscription. |

### How the repeating window works

`repeating` is **time-based, not count-based**. The discount applies to every invoice whose creation date falls within the window — it is not a fixed number of billing cycles.

The window is calculated as:

```
window start  =  date the discount was attached to the subscription
window end    =  window start + durationInMonths  (exclusive)
```

For example, a user signs up on **April 17** for a **30-day plan** with a **3-month repeating voucher**. The discount window runs **April 17 → July 18** (July 18 exclusive, so the last eligible day is July 17). That window covers **4 invoices** — not 3:

| Invoice | Created | Discounted? |
|---|---|---|
| 1 (subscription creation) | Apr 17 | ✅ |
| 2 (1st renewal) | May 17 | ✅ |
| 3 (2nd renewal) | Jun 16 | ✅ |
| 4 (3rd renewal) | Jul 16 | ✅ |
| 5 (4th renewal) | Aug 15 | ❌ window closed |

The number of discounted invoices depends on the billing cycle length relative to the duration window.

<Note type="info">
**`once` vs. `durationInMonths: 1`**

These are not equivalent. `once` is count-based: it applies to the very first invoice only. A `repeating` voucher with `durationInMonths: 1` is time-based: it applies to every invoice created within the next calendar month, which could be multiple invoices on short billing cycles.

Count-based repeating vouchers (e.g., "apply the discount for exactly N renewals") are not supported. Use `once` if you need the discount applied only to the first invoice.
</Note>

Once the recurrence window closes, subsequent invoices reflect full pricing.

## Using Vouchers to apply Discounts

### Creating a new Voucher

In order to apply a discount for a new subscription, a voucher needs to be created first.

The voucher can be used once or for every subscription requiring the same discount. When creating a voucher, you can specify either a fixed discount amount or a percentage discount.

The recurrence indicates the discount validity. It can be `once` for the first invoice only, `forever` for every invoice, or `repeating` for all invoices created within a time window of `durationInMonths` months. See [Validity](#validity) for details on how the repeating window is calculated.

If no existing voucher should be used, [a new voucher has to be created](/billing/vouchers#create-a-voucher).

<CodeGroup title="Creating a Voucher">

```bash
curl --request POST \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/vouchers" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Monthly Basic",
    "priceDiscountPercentage": 10,
    "recurrence":{
        "type": "repeating",
        "durationInMonths": 3
    }
  }'
```

</CodeGroup>

The [returned voucher's ID](/billing/schemas/voucher) can then be used during subscription or quote creation.

### Using a Voucher

A voucher can be used to apply discounts to either quotes or subscriptions.

#### For a new Quote

In order to apply a discount to a quote, a voucher ID needs to be specified during [quote creation](/billing/quotes#create-a-quote). 
The ID of the used voucher is also returned in the [created quote](/billing/schemas/quote).

Note that creating a quote with a voucher does not increase the redemption count of a voucher.

<CodeGroup title="Creating a Quote with a Voucher">

```bash
curl --request POST \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/quotes" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", 
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", 
    "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
  }'
```

</CodeGroup>

#### For a new Subscription

To use a discount for a new subscription, a voucher ID needs to be specified in the billing details when [creating the subscription](/core/subscriptions#create-a-subscription).

<CodeGroup title="Creating a Subscription with a Voucher">

```bash
curl --request POST \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", 
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", 
    "billing": {
      "discount": {
        "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
      } 
    } 
  }'
```

</CodeGroup>

### Retiring a Voucher

A voucher [can be retired](/billing/vouchers#retire-a-voucher) so that it can no longer be used when creating a subscription.

Retiring a voucher does not have any effect on any subscriptions that are already using it. The response will contain the updated voucher with a `retiredReason` set and its status updated.

<CodeGroup title="Retiring a Voucher">

```bash
curl --request POST \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/vouchers/vou_0SNlurA049MEWV0h2jfjkdiOdplN/retire" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json"
```

</CodeGroup>