# Promotion codes

> The codes customers type to redeem a coupon, each with its own limits.

Source: https://docs.borga.is/api/promotion-codes

A promotion code redeems a [coupon](/api/coupons). It can be restricted to one customer, limited in redemptions and given an expiry, all within the coupon's own limits. Codes are upper-cased and unique among your codes. Redeem one on a [subscription](/api/subscriptions) with `promotion_code`, on a [checkout session](/api/payment-sessions) that starts a subscription, or price it first with a [quote](/api/subscriptions#quote-a-subscription).

**The promotion code object**

- `id` (string): Prefixed `promo_`.
- `object` (string): `promotion_code`
- `code` (string): What the customer types.
- `coupon` (string)
- `customer` (string | null): The only customer who may use it, when restricted.
- `max_redemptions` (integer | null)
- `expires_at` (timestamp | null)
- `times_redeemed` (integer)
- `active` (boolean)
- `metadata` (object)
- `created_at` (timestamp)
- `updated_at` (timestamp)

## Create a promotion code

`POST /v1/promotion_codes`

**Body**

- `coupon` (string, required): An active coupon.
- `code` (string): 3 to 40 letters, digits and dashes. Generated when omitted.
- `customer` (string): Restrict the code to this customer.
- `max_redemptions` (integer)
- `expires_at` (timestamp)
- `metadata` (object)

Errors: [`resource_not_found`](/errors/resource_not_found) for the coupon or customer, [`resource_in_wrong_state`](/errors/resource_in_wrong_state) for a retired coupon, [`resource_already_exists`](/errors/resource_already_exists) for a code in use.

## Retrieve a promotion code

`GET /v1/promotion_codes/:id`

## Update a promotion code

`POST /v1/promotion_codes/:id`

**Body**

- `active` (boolean): `false` retires the code; `true` brings it back while its coupon is active.
- `customer` (string | null): Restrict to one customer, or `null` to lift the restriction.
- `metadata` (object)

Errors: [`resource_not_found`](/errors/resource_not_found) for the code or customer, [`resource_in_wrong_state`](/errors/resource_in_wrong_state) for bringing back a code whose coupon is retired.

## List promotion codes

`GET /v1/promotion_codes`

**Query parameters**

- `coupon` (string)
- `code` (string): An exact code.
- `limit` (integer, default 25)
- `starting_after` (string)