Offers
Define reusable introductory and promotional pricing terms.
An Offer is the canonical catalog resource for temporary subscription pricing. It scopes one or more phases to plan prices, controls when those terms are available, and creates an immutable application when accepted.
Offer types
| Purpose | Selection | Scope | Supported phases |
|---|---|---|---|
introductory | Applied automatically to an eligible new subscription | Exactly one base plan price | Optional free_trial, plus at most one percentage or amount_off phase |
promotional | Selected with offerId or referenced by a Promo Code | One or more base plan prices | One or more percentage, amount_off, or fixed_price phases |
Price variants inherit Offers from their base price. An Offer cannot target a variant directly.
Catalog and accepted terms
The Offer is the editable catalog definition. It contains:
purpose, which determines how Commet selects itplanPriceIds, which limit where it can apply- ordered
phases, which define the pricing change and duration startsAt,endsAt, andactive, which control future availabilitymetadatafor your own identifiers
When checkout accepts an Offer, Commet records an Offer Application with the resolved currency, subtotal, discount, total, and phases. Updating, deactivating, or archiving the catalog Offer does not rewrite an existing application.
Create an Offer
const offer = await commet.offers.create({
name: 'Launch pricing',
purpose: 'promotional',
planPriceIds: ['pp_pro_monthly'],
phases: [
{ type: 'percentage', durationCycles: 3, percentage: 5000 },
],
startsAt: '2026-08-01T00:00:00.000Z',
endsAt: '2026-09-01T00:00:00.000Z',
})Use the Offers API to list, retrieve, create, replace, and archive catalog definitions. API v8 is required.
Related
How is this guide?