# Coupons

`GET https://api.tentary.com/v1/coupons`

Source: https://tentary.com/en/help/api/list-coupons/
Area: Coupons
MCP tool: `list_coupons`. Reads only. Changes nothing in the account.

---

The coupons (discount codes), newest first: code, status, state, percent or amount, uses and use limit, start and end day, the products they apply to (with their status `live`, `draft`, `archived` or `deleted`), and admin links.

`status` is what you set: `active` or `archived`. Without `status`, the list has active coupons only. Archived coupons are deleted coupons.

`state` is the result for buyers, and read only:

- `valid`: buyers can use the code now.
- `scheduled`: the start is in the future.
- `expired`: the end is in the past.
- `used_up`: the use limit is reached.
- `archived`: deleted.
- `no_products`: the coupon applies to no live product. The checkout sells only live products.
- `reserved`: open checkouts of the last hour hold the remaining uses. They become free again if the buyers do not pay.

The fields have the same names and formats as in [`POST /v1/coupons`](https://tentary.com/en/help/api/create-coupon/) and [`PATCH /v1/coupons/{coupon_id}`](https://tentary.com/en/help/api/update-coupon/).

## Authorization

`Authorization: Bearer <API key>`

A personal API key (tnt_...). Create it in the Tentary app on the page AI & API.

## Query parameters

- `status` (string, query): active (default) or archived. Allowed values: `active`, `archived`.
- `cursor` (string, query): next_cursor of the previous page. Send the same filters and limit again: the cursor does not keep them. Leave out for the first page.
- `limit` (integer, query): Items per page, default 25. Limits: min 1, max 50.

## Response

- `coupons` (array of object): Newest first.
  - `id` (integer): The ID.
  - `code` (string): The code buyers type.
  - `status` (string): What the seller set. archived = deleted. Allowed values: `active`, `archived`.
  - `state` (string): The result for buyers: valid = buyers can use the code now. Allowed values: `valid`, `scheduled`, `expired`, `used_up`, `reserved`, `archived`, `no_products`.
  - `percent` (integer, can be null): Discount in percent, or null for a fixed amount.
  - `amount` (string, can be null): Decimal string, like "19.90". Fixed discount, or null for a percent discount.
  - `currency` (string): Currency code, like EUR.
  - `used` (integer): How often the code was used.
  - `max_uses` (integer, can be null): null = no limit.
  - `reserved_in_open_checkouts` (integer): Uses held by open checkouts of the last hour.
  - `starts_on` (string<date>, can be null): Like 2026-01-31. First day the code works.
  - `ends_on` (string<date>, can be null): Like 2026-01-31. The code stops at the start of this day.
  - `product_ids` (array of integer, can be null): null = all products. [] = no product.
  - `products` (array of object): The products of product_ids (the first 200).
    - `id` (integer): The ID.
    - `name` (string, can be null): The name.
    - `status` (string): The status. Allowed values: `live`, `draft`, `archived`, `deleted`.
  - `created_at` (string<date-time>, can be null): UTC, like 2026-01-31T14:05:00Z.
  - `admin_url` (string<uri>): The page in the Tentary app.
- `next_cursor` (string, can be null): Send it as cursor for the next page, with the same filters and limit. null = this is the last page.
- `links` (object): Pages in the Tentary app or on tentary.com.
  - `coupons` (string<uri>): Page in the Tentary app.
  - `new_coupon` (string<uri>): Page in the Tentary app.

## Example request

```bash
curl "https://api.tentary.com/v1/coupons" \
  -H "Authorization: Bearer $TENTARY_API_KEY"
```

## Example response

```json
{
  "coupons": [
    {
      "id": 701,
      "code": "SPRING20",
      "status": "active",
      "state": "valid",
      "percent": 20,
      "amount": null,
      "currency": "EUR",
      "used": 12,
      "max_uses": 100,
      "reserved_in_open_checkouts": 0,
      "starts_on": null,
      "ends_on": "2026-11-26",
      "product_ids": null,
      "products": [],
      "created_at": "2026-09-27T10:00:00Z",
      "admin_url": "https://app.tentary.com/discounts/edit/701"
    }
  ],
  "next_cursor": null,
  "links": {
    "coupons": "https://app.tentary.com/discounts",
    "new_coupon": "https://app.tentary.com/discounts/new"
  }
}
```