Offerings

Offerings are the customer-facing packaging layer. They wrap one or more rate plans into a subscribable plan with a name, description, billing mode, trial configuration, and storefront display options.

Think of an offering as the product listing a customer sees — "Starter Plan — $49/month + usage" — while the underlying rate plans define exactly how usage is priced.

Billing Modes

Mode	Description	Best For
`POSTPAID`	Charge at end of billing period based on actual usage	API products, metered services
`PREPAID`	Customer buys credits upfront; usage draws down the wallet	AI tokens, compute credits
`HYBRID`	Base fee charged upfront, overages charged postpaid	SaaS + API combos

Prepaid / wallet

In PREPAID mode, customers fund a wallet before using your service and usage draws it down. You can optionally enable escrow — holds placed against the wallet for in-flight usage so a customer can't overspend a balance mid-request. Escrow is configured with flat fields on the offering (not a nested escrowConfig object):

escrowEnabled — turn holds on or off.
escrowMode — how the hold amount is estimated: FULL, PARTIAL, or ESTIMATED.
escrowScope — PER_REQUEST (hold per call) or PER_PERIOD (hold for the period).
escrowTimeoutMin — how long an unused hold is kept before it's released.

Trial Periods

Set trialDays to offer a free trial before billing starts:

{
  "name": "Starter — 14-day free trial",
  "trialDays": 14,
  "billingMode": "POSTPAID"
}

When a subscription is created, it enters TRIALING status. After trialDays elapses, Aforo automatically converts to ACTIVE and begins charging.

ℹ

If a customer migrates to a different plan while still in a trial, the trial period carries over to the new plan — the customer doesn't lose unused trial days.

FX strategy

The fxStrategy field accepts FIXED_AT_INVOICE, SPOT_RATE, or MONTHLY_AVERAGE.

ℹ

Today the service locks the effective strategy to FIXED_AT_INVOICE regardless of what you send — the exchange rate is fixed at the moment the invoice is cut. The other two values are reserved for a future release; treat FX as fixed-at-invoice for now.

Creating an Offering

Go to Pricing Studio → Offerings
Click + New Offering
Select one or more rate plans (Step 1)
Configure billing mode, trial, escrow settings (Step 2)
Review and publish (Step 3)

Modification guard

Aforo protects active offerings from destructive changes. If customers are actively subscribed, these changes are blocked:

Removing a rate-plan item
Changing the billing currency
Changing the offering type
Changing the billing mode

Safe changes — name, description, tags, adding an item — are always allowed. Check the impact before editing; the guard returns an ALLOW/BLOCK verdict plus the active-subscriber count:

GET/api/v1/offerings/{id}/modification-check?changes=REMOVE_ITEM,CHANGE_TYPEALLOW / BLOCK + active-subscriber count

Offering type & visibility

An offering has an offeringType — STANDALONE, BUNDLE, or ADDON — and, for bundles, a pricingMode of PER_PRODUCT or BUNDLE_PRICE.

There is no published boolean. Storefront visibility is driven by two fields: status (DRAFT / ACTIVE / ARCHIVED) and visibility (PUBLIC, RESTRICTED — limited to listed customers — or INVITE_ONLY). An offering shows on your customer-facing pricing page when it's ACTIVE and PUBLIC; keep it DRAFT while you build it.