# Discounts

Discount codes applied at checkout, either a `percentage` off or a `fixed`
amount off. All discount endpoints require the `events:write` scope.

A serialized discount object:

```json
{
  "id": "664f0a1b2c3d4e5f60718293",
  "code": "SUMMER20",
  "type": "percentage",
  "value": 20,
  "max_uses": 500,
  "used_count": 42,
  "expires_at": "2026-09-01T00:00:00.000Z",
  "active": true,
  "created_at": "2026-06-05T10:00:00.000Z"
}
```

For `type: "percentage"`, `value` is a percent (`0`–`100`). For
`type: "fixed"`, `value` is an amount in your currency.

---

## GET /v1/discounts

List your discount codes, newest first.

**Scope:** `events:write`

### Query params

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | No | Page size, `1`–`100` (default `20`). |
| `starting_after` | string | No | Cursor — a discount id to page after. |

### Example request

```bash
curl https://api.ticketconnect.example/v1/discounts \
  -H "Authorization: Bearer sk_test_your_key_here"
```

### Example response

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    { "id": "664f0a1b2c3d4e5f60718293", "code": "SUMMER20", "type": "percentage", "value": 20, "max_uses": 500, "used_count": 42, "expires_at": "2026-09-01T00:00:00.000Z", "active": true, "created_at": "2026-06-05T10:00:00.000Z" }
  ]
}
```

---

## POST /v1/discounts

Create a discount code. If you omit `code`, a random one is generated.

**Scope:** `events:write`

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | Yes | `percentage` or `fixed`. |
| `value` | number | Yes | Non-negative amount. For `percentage`, must be `0`–`100`. |
| `code` | string | No | The code customers enter. Generated if omitted. |
| `max_uses` | integer | No | Maximum redemptions. |
| `expires_at` | string | No | Expiry timestamp (ISO 8601). |
| `event_ids` | string[] | No | Restrict the code to specific events. |

Accepts an `Idempotency-Key` header.

### Example request

```bash
curl https://api.ticketconnect.example/v1/discounts \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER20",
    "type": "percentage",
    "value": 20,
    "max_uses": 500,
    "expires_at": "2026-09-01T00:00:00Z"
  }'
```

### Example response

```json
{
  "id": "664f0a1b2c3d4e5f60718293",
  "code": "SUMMER20",
  "type": "percentage",
  "value": 20,
  "max_uses": 500,
  "used_count": 0,
  "expires_at": "2026-09-01T00:00:00.000Z",
  "active": true,
  "created_at": "2026-06-05T10:00:00.000Z"
}
```

---

## GET /v1/discounts/{id}

Retrieve a discount code by id.

**Scope:** `events:write`

### Path params

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Discount id. |

### Example request

```bash
curl https://api.ticketconnect.example/v1/discounts/664f0a1b2c3d4e5f60718293 \
  -H "Authorization: Bearer sk_test_your_key_here"
```

### Example response

```json
{
  "id": "664f0a1b2c3d4e5f60718293",
  "code": "SUMMER20",
  "type": "percentage",
  "value": 20,
  "max_uses": 500,
  "used_count": 42,
  "expires_at": "2026-09-01T00:00:00.000Z",
  "active": true,
  "created_at": "2026-06-05T10:00:00.000Z"
}
```

---

## PATCH /v1/discounts/{id}

Update mutable fields on a discount. `value` is written against the discount's
existing type (percentage values are still capped at `100`).

**Scope:** `events:write`

### Path params

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Discount id. |

### Request body

All fields optional; send only what you want to change.

| Field | Type | Description |
| --- | --- | --- |
| `value` | number | New non-negative value. |
| `max_uses` | integer | New maximum redemptions. |
| `expires_at` | string \| null | New expiry, or `null` to clear it. |
| `active` | boolean | Enable or disable the code. |

### Example request

```bash
curl https://api.ticketconnect.example/v1/discounts/664f0a1b2c3d4e5f60718293 \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -X PATCH \
  -d '{ "active": false, "max_uses": 1000 }'
```

### Example response

```json
{
  "id": "664f0a1b2c3d4e5f60718293",
  "code": "SUMMER20",
  "type": "percentage",
  "value": 20,
  "max_uses": 1000,
  "used_count": 42,
  "expires_at": "2026-09-01T00:00:00.000Z",
  "active": false,
  "created_at": "2026-06-05T10:00:00.000Z"
}
```

---

## DELETE /v1/discounts/{id}

Delete a discount code.

**Scope:** `events:write`

### Path params

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Discount id. |

### Example request

```bash
curl https://api.ticketconnect.example/v1/discounts/664f0a1b2c3d4e5f60718293 \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -X DELETE
```

### Example response

```json
{ "id": "664f0a1b2c3d4e5f60718293", "deleted": true }
```