Discounts and promo codes

Discounts let you reduce the price of a customer's Subscription — a percentage or a fixed amount — for one or more billing cycles. There are two ways to put a Discount in a customer's hands:

• Apply it yourself — attach a Discount to a specific customer's active Subscription from the Clerk Dashboard.
• Issue a promo code — publish a code that customers redeem themselves at checkout.

Use cases

Discounts simplify common billing workflows:

• Negotiated pricing - Honor a discount your sales team agreed to during contract discussions.
• Loyalty rewards - Reward early adopters or community advocates with reduced pricing.
• Customer goodwill - Make things right after a service issue or rough support experience.
• Promotional campaigns - Share a promo code for a launch, event, or partnership and let customers redeem it themselves.

How Discounts work

• A Discount defines the reduction: its type (percentage or fixed amount), its amount, how many billing cycles it lasts, and how it's redeemed. You can apply the same Discount to any number of customers.
• An Applied Discount is that Discount on a specific customer's Subscription Item, where its terms become an actual price reduction: the amount deducted from each charge and the billing cycles remaining.

When you create a Discount, you configure:

• Type and amount - A percentage (e.g. 20% off) or a fixed amount (e.g. $50 off). You can configure different amounts for monthly and annual billing periods.
• Duration - The number of billing cycles the Discount applies for, or indefinitely.
• Redemption - Whether you apply the Discount yourself (Manual) or customers redeem it with a code at checkout (Promo code). Promo codes have additional settings: the code, when it's available, an optional redemption limit, whether it's restricted to new subscribers, and which plans it applies to.

After you create a Discount, you can edit its name and description, and add eligible plans to a promo code. All other fields are immutable. To stop using a Discount, archive it and create a new one.

On each renewal, Clerk applies the customer's Applied Discount before charging their payment method and decrements its remaining billing cycles. When no cycles remain, the Applied Discount is exhausted and future renewals are charged at full price.

Create a Discount

1. In the Clerk Dashboard, navigate to the Discounts⁠ page.
2. Select Add discount.
3. Give the Discount a name and key, and optionally a description to record why it exists.
4. Configure the amount — a percentage or a fixed amount — for each billing period you want to discount. Monthly and annual periods can have different amounts.
5. Set the Duration to a number of billing cycles, or select Forever.
6. Choose how the Discount is redeemed:
   • Manual - You'll apply it yourself to specific customers.
   • Promo code - Enter the code customers will type at checkout, or generate a random 10-character alphanumeric code, great for single-use promo codes. Set its Availability dates, then optionally limit total redemptions, restrict the code to new subscribers, and select which plans it can be redeemed on.

Apply a Discount

For a Manual Discount, you apply it to a customer's Subscription Item yourself. You can apply a Discount to any active or past due Subscription Item on a paid plan:

1. Navigate to the Billing⁠ page in the Clerk Dashboard.
2. Select the subscriber you want to apply a Discount to.
3. Select the ... menu next to the Subscription Item you want to discount.
4. Choose Apply discount and select the Discount to apply.

The dialog previews the customer's current price and their new discounted price. The Discount takes effect on the Subscription's next charge.

Promo codes

A promo code is a Discount that customers redeem themselves at checkout, rather than one you apply to their Subscription. Create the Discount with a Promo code redemption type (see Create a Discount), then share the code with your customers.

• Code - The string customers enter at checkout, e.g. LAUNCH20. Enter your own or generate a random promo code.
• Limit total redemptions - Optionally cap the total number of times the code can be redeemed across all customers. Leave it off for unlimited redemptions.
• New subscribers only - Optionally restrict the code to customers who have never had a paid Subscription.
• Select plans - The plans the code can be redeemed on.
• Availability - The date range during which the code can be redeemed.

When a customer enters a valid code at checkout, its Discount is reflected in the checkout totals and applied to their Subscription Item for its configured duration. From the Discounts⁠ page, you can see how many times a code has been redeemed.

Promo code events

When a customer applies or removes a promo code during checkout, Clerk records an event in the instance's Application Logs:

Revoke an Applied Discount

Revoking an Applied Discount stops it from affecting future charges. Charges that already happened are unaffected, and the customer's next renewal returns to full price. This works the same whether the Discount was applied manually or redeemed with a promo code.

1. Navigate to the Billing⁠ page in the Clerk Dashboard.
2. Select the subscriber.
3. Select the ... menu next to the discounted Subscription Item.
4. Choose Revoke discount.

Archive a Discount

Archiving a Discount prevents it from being applied to any new Subscriptions and, for a promo code, stops the code from being redeemed. Existing Applied Discounts are unaffected, and customers who already have the Discount keep it until it's exhausted or revoked.

1. In the Clerk Dashboard, navigate to the Discounts⁠ page.
2. Select the Discount you want to archive.
3. Select Archive discount, then confirm.

What your customers experience

Applied Discounts are reflected everywhere your customers see billing information:

• Checkout - Totals reflect the Discount at checkout time. For promo codes, customers select Add promo code, enter their code, and see the discount applied before they pay.
• Statements and payment history - Each payment shows the Discount and the amount deducted.
• Email receipts - Notifications display the amount deducted from the subtotal, the same way account credits are displayed.

Webhook events

If you sync Subscription data to your own systems, Discount information is included in subscription item webhook payloads: applying or revoking a Discount emits a subscriptionItem.updated event, and Subscription Item payloads include the Applied Discount's details whenever one is in effect. This applies to both manually applied Discounts and promo code redemptions.

See the Billing webhooks documentation for the full list of Billing webhook events.