# Coupons

> Reusable discounts on subscription invoices, applied by id or through a promotion code.

Source: https://docs.borga.is/api/coupons

A coupon is a percentage or a fixed amount off a subscription's cycle invoices: for the next invoice (`once`), for a number of months (`repeating`) or for good (`forever`). Apply it to a subscription by id, or hand out [promotion codes](/api/promotion-codes) that redeem it. The subscription keeps a snapshot of the discount, so editing or retiring the coupon never changes a running discount. The discount is taken off the lines' total and VAT is computed on what the customer pays; see [subscriptions](/billing/subscriptions).

**The coupon object**

- `id` (string): Prefixed `cpn_`.
- `object` (string): `coupon`
- `name` (string)
- `percent_off` (number | null): Percentage off each discounted invoice.
- `amount_off` (integer | null): Fixed amount off, in minor units of `currency`.
- `currency` (string | null): The currency of `amount_off`.
- `duration` (enum): `once`, `repeating` or `forever`.
- `duration_in_months` (integer | null): For `repeating`.
- `max_redemptions` (integer | null)
- `redeem_by` (timestamp | null): After this the coupon can no longer be applied.
- `times_redeemed` (integer)
- `active` (boolean): `false` once retired. Running discounts keep going.
- `metadata` (object)
- `created_at` (timestamp)
- `updated_at` (timestamp)

## Create a coupon

`POST /v1/coupons`

**Body**

- `name` (string, required)
- `percent_off` (number): 0 to 100. Give this or `amount_off`.
- `amount_off` (integer): In minor units; needs `currency`. Give this or `percent_off`.
- `currency` (string): With `amount_off`. Subscriptions in another currency cannot use the coupon.
- `duration` (enum, default forever): `once`, `repeating` or `forever`.
- `duration_in_months` (integer): Required with `repeating`, refused otherwise.
- `max_redemptions` (integer): Across every code and direct application.
- `redeem_by` (timestamp)
- `metadata` (object)

```bash
curl https://api.borga.is/v1/coupons \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring 20%", "percent_off": 20, "duration": "repeating", "duration_in_months": 3 }'
```

Errors: [`invalid_field`](/errors/invalid_field) for both or neither of `percent_off` and `amount_off`, [`missing_field`](/errors/missing_field) for `currency` or `duration_in_months`.

## Retrieve a coupon

`GET /v1/coupons/:id`

## Update a coupon

`POST /v1/coupons/:id`

The discount itself cannot change; create a new coupon and retire this one.

**Body**

- `name` (string)
- `active` (boolean): `false` retires the coupon.
- `metadata` (object)

## List coupons

`GET /v1/coupons`

**Query parameters**

- `limit` (integer, default 25)
- `starting_after` (string)