# Create coupon

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

Source: https://tentary.com/en/help/api/create-coupon/
Area: Coupons
MCP tool: `create_coupon`. Changes data at once.

---

Creates a coupon (discount code). It works at once, or from `starts_on`.

The answer is the coupon, as in [`GET /v1/coupons`](https://tentary.com/en/help/api/list-coupons/), with its `state`.

## Authorization

`Authorization: Bearer <API key>`

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

## Request body

- `code` (string, required): The code buyers type, like SUMMER20. Unique in the shop (upper and lower case count as the same). Limits: minLength 1, maxLength 255.
- `percent` (integer): Discount in percent. Give percent or amount. Limits: min 1, max 100.
- `amount` (number | string): Fixed discount. Amount in the account currency, like 49 or 19.99. Limits: above 0, pattern ^[0-9]{1,9}(\.[0-9]{1,2})?$.
- `max_uses` (integer): How often the code can be used in total. 0 = no limit. On create, left out = no limit. On update, left out = no change, null removes the limit. Limits: min 0.
- `starts_on` (string): First day the code works, like 2026-11-27. On create, left out = at once. On update, left out = no change, null removes the date. Limits: pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}$.
- `ends_on` (string): The code stops at the start of this day (00:00). On create, left out = no end. On update, left out = no change, null removes the date. Limits: pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}$.
- `product_ids` (array of integer, can be null): Only these products (ids from list_products). null = all products. On create, left out = all products. On update, left out = no change. [] = no product (the code works nowhere). Limits: maxItems 200.

## Response

- `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.

## Example request

```bash
curl -X POST "https://api.tentary.com/v1/coupons" \
  -H "Authorization: Bearer $TENTARY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "RUNNER15",
  "percent": 15,
  "max_uses": 50,
  "product_ids": [
    102
  ]
}'
```

## Example response

```json
{
  "id": 702,
  "code": "RUNNER15",
  "status": "active",
  "state": "valid",
  "percent": 15,
  "amount": null,
  "currency": "EUR",
  "used": 0,
  "max_uses": 50,
  "reserved_in_open_checkouts": 0,
  "starts_on": null,
  "ends_on": null,
  "product_ids": [
    102
  ],
  "products": [
    {
      "id": 102,
      "name": "Morning Yoga in 30 Days",
      "status": "live"
    }
  ],
  "created_at": null,
  "admin_url": "https://app.tentary.com/discounts/edit/702"
}
```