# Apply discount to subscription

`POST https://rcur.app/api/v2/subscriptions/{subscriptionId}/discount`

With a discount code, or a discount without a code. A subscription has at most one
discount at a time.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `subscriptionId` | string | yes |  |

## Request body

Either discount_id, or type, value and duration for a discount without a code. It applies from the next payment.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `discount_id` | string | no | Id of a discount code; counts towards its maximum |
| `type` | string | no | One of: `percentage`, `fixed`. |
| `value` | number | no | A percentage, or an amount in the currency of the subscription |
| `duration` | string | no | One of: `once`, `repeating`, `forever`. |
| `periods` | integer | no | Required for repeating |

## Example request

```bash
curl -X POST https://rcur.app/api/v2/subscriptions/YJRQAMRQ6y/discount \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "discount_id": "aB3dE5fG7h",
  "type": "percentage",
  "value": 10,
  "duration": "repeating",
  "periods": 3
}'
```

## Responses

### 201 Discount applied to the subscription

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `discount_id` | string | no | The discount code it came from; null for a discount without a code |
| `code` | string | no |  |
| `type` | string | yes | One of: `percentage`, `fixed`. |
| `value` | string | yes |  |
| `currency` | string | no |  |
| `duration` | string | yes | One of: `once`, `repeating`, `forever`. |
| `periods_total` | integer | no |  |
| `periods_used` | integer | yes |  |
| `total_discounted` | string | yes |  |
| `created_at` | string | no |  |

```json
{
    "discount_id": "aB3dE5fG7h",
    "code": "SUMMER25",
    "type": "percentage",
    "value": "25.00",
    "currency": "EUR",
    "duration": "repeating",
    "periods_total": 3,
    "periods_used": 1,
    "total_discounted": "7.50",
    "created_at": "2026-05-20 10:00:00"
}
```

### 404 Resource not found

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | integer | yes |  |
| `error` | string | yes |  |

```json
{
    "status": 404,
    "error": "Resource not found"
}
```

### 422 Validation error

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | integer | yes |  |
| `error` | string | yes |  |
| `fields` | object | no |  |

```json
{
    "status": 422,
    "error": "Could not process request. Some fields contain invalid data",
    "fields": {
        "email": [
            "The email field is required."
        ]
    }
}
```