---
title: "Apply a discount to a subscription item"
method: POST
path: "/billing/subscription_items/{subscription_item_id}/discounts"
tags: ["Billing"]
---

# Apply a discount to a subscription item

`POST /billing/subscription_items/{subscription_item_id}/discounts`

Applies an existing discount to a subscription item.
Manual application is an override path: self-serve distribution rules are not enforced.
At most one active discount is allowed per subscription item; applying a different
discount replaces the currently active one. Re-applying the same active discount returns a conflict.

## Path parameters

- `subscription_item_id` string, required

## Request body

- ApplyCommerceDiscountRequest
  - `discount_id` string, required — The ID of the discount to apply to the subscription item.

## Response `200`

A commerce discount redemption.

- CommerceDiscountRedemptionResponse
  - `object` 'commerce_discount_redemption', required — String representing the object's type. Objects of the same type share the same value.
  - `id` string, required — Unique identifier for the discount redemption.
  - `subscription_item_id` string, required — Unique identifier for the subscription item the discount was applied to.
  - `discount_id` string, required — Unique identifier for the discount that was applied.
  - `name` string — The display name of the discount.
  - `source` 'promotion' | 'manual' | 'promo_code', required — How the discount was applied to the subscription item.
  - `promo_code` string — The promo code used to redeem the discount, when applicable.
  - `effect` 'percentage' | 'fixed_amount' — The snapshotted discount effect.
  - `percent_off` number, double, nullable — Percent off when the effect is percentage.
  - `amount_off` CommerceMoneyResponse
    - `amount` integer, required — The amount in cents.
    - `amount_formatted` string, required — The formatted amount as a string (e.g., "$49.99").
    - `currency` string, required — The currency code (e.g., "USD").
    - `currency_symbol` string, required — The currency symbol (e.g., "$").
  - `amount` CommerceMoneyResponse
    - `amount` integer, required — The amount in cents.
    - `amount_formatted` string, required — The formatted amount as a string (e.g., "$49.99").
    - `currency` string, required — The currency code (e.g., "USD").
    - `currency_symbol` string, required — The currency symbol (e.g., "$").
  - `cycles_remaining` integer, nullable, required — Remaining billing cycles the discount applies to. Null means the discount lasts forever.
  - `cycles_applied` integer, required — Number of billing cycles the discount has already been applied to.
  - `status` 'active' | 'exhausted' | 'removed' — Current status of the discount redemption.
  - `redeemed_at` integer, required — Unix timestamp (in milliseconds) when the discount was redeemed.
  - `redeemed_by` string, nullable, required — Identifier of the actor that redeemed the discount, when available.

## Other responses

- `400` — Request was not successful
- `401` — Authentication invalid
- `403` — Authorization invalid
- `404` — Resource not found
- `409` — Conflict
- `422` — Invalid request parameters
- `500` — Request was not successful

---

[API](https://skmtc.net/clerk/apis/clerk-backend-api.md) · [All operations](https://skmtc.net/clerk/apis/clerk-backend-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clerk/clerk-backend-api/revisions/75df3a43fcb2/schema)