Promotional Offers
Apply explicit campaign, retention, and experiment pricing with offerId.
A Promotional Offer is an Offer with purpose: 'promotional'. Your integration selects it explicitly with offerId, or a Promo Code references it for customer-entered distribution.
Supported phases
Promotional Offers support one or more ordered phases:
percentagereduces the base plan price by basis points.amount_offsubtracts an explicit amount for each supported checkout currency.fixed_pricereplaces the base plan price with an explicit amount for each supported checkout currency.
Each phase has a positive durationCycles. Promotional Offers cannot contain a free-trial phase.
const offer = await commet.offers.create({
name: 'Launch sequence',
purpose: 'promotional',
planPriceIds: ['pp_pro_monthly'],
phases: [
{ type: 'percentage', durationCycles: 2, percentage: 5000 },
{ type: 'percentage', durationCycles: 2, percentage: 2500 },
],
})Currency-specific phases must define every supported checkout currency. Commet does not silently reuse a USD amount in another currency.
Select an Offer
Pass the Offer ID when creating a subscription:
await commet.subscriptions.create({
customerId: 'user_123',
planCode: 'pro',
offerId: offer.id,
})An explicit Promotional offerId overrides the automatic Introductory Offer. It cannot be combined with promoCode, customTrialDays, or skipTrial: true.
Supported plan-change, preview, and reactivation operations also accept offerId. The Offer must be active, inside its availability window, and scoped to the resolved base price.
Distribute with Promo Codes
A Promo Code references one Promotional Offer. An Offer referenced by a code must remain a single percentage or amount_off phase; it cannot be multi-phase or use fixed_price.
Use offerId when your application decides who receives the pricing. Use a Promo Code when the customer enters a campaign code at checkout.
Accepted terms
Checkout stores an immutable Offer Application. Later catalog edits affect future acceptances only. The discount changes the plan base price; usage overage, seats, and add-on charges remain undiscounted.
Related
How is this guide?