Clerk API (unofficial showcase)
POST/billing/subscription_items/{subscription_item_id}/discounts

Apply a discount to a subscription item

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.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 1 body field
subscription_item_idstringrequired
The ID of the subscription item to apply the discount to

Parameters for applying the discount

discount_idstringrequired
The ID of the discount to apply to the subscription item.

8 status codes
200A commerce discount redemption.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:commerce_discount_redemption
idstringrequired
Unique identifier for the discount redemption.
subscription_item_idstringrequired
Unique identifier for the subscription item the discount was applied to.
discount_idstringrequired
Unique identifier for the discount that was applied.
namestringoptional
The display name of the discount.
sourcestringrequired
How the discount was applied to the subscription item.
Allowed:promotionmanualpromo_code
promo_codestringoptional
The promo code used to redeem the discount, when applicable.
effectstringoptional
The snapshotted discount effect.
Allowed:percentagefixed_amount
percent_offnumberoptional
Percent off when the effect is percentage.
amount_offobjectoptional
Fixed amount off when the effect is fixed_amount.
amountobjectoptional
How much this discount takes off the subscription item's next renewal charge. Present for either effect when next-payment data is available.
cycles_remainingintegerrequired
Remaining billing cycles the discount applies to. Null means the discount lasts forever.
cycles_appliedintegerrequired
Number of billing cycles the discount has already been applied to.
statusstringoptional
Current status of the discount redemption.
Allowed:activeexhaustedremoved
redeemed_atintegerrequired
Unix timestamp (in milliseconds) when the discount was redeemed.
redeemed_bystringrequired
Identifier of the actor that redeemed the discount, when available.
400Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
401Authentication invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Authorization invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Resource not found
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
409Conflict
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Invalid request parameters
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
500Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 401 is returned: Authentication invalid. A 403 is returned: Authorization invalid. A 404 is returned: Resource not found. A 409 is returned: Conflict. A 422 is returned: Invalid request parameters. A 500 is returned: Request was not successful.