PricingCreditBenefit

Credits that come with a charge, such as the 500 credits a month included with a plan's platform fee. Each allocation is granted to the customer on the order's billing cycles and expires at the end of its allocation period, apart from what rolls over. Usage priced in credits (UsagePrepaidCredits and similar) spends them as signals arrive: a seat's credits before the customer's shared ones, credits already granted before ones waiting on an invoice (creditGrantTiming), and the soonest to expire first. Beyond them, credits are billed at the overage price. When you send a benefit, only amount is required; responses show every field, with its default.

amount
Type: number
min:
0
required

Credits for each billing period of the charge (a quarterly charge's amount covers the quarter), handed out as allocationCadence says. On a one-time charge, granted once, when the charge starts, and multiplied by the charge's quantity. With recipient: seat, each seat gets this many.
allocationCadence
Type: stringenum

How often the credits are handed out, on the order's billing cycles. monthly, quarterly, semiAnnually and annual hand out the share of the billing period's amount for 1, 3, 6 or 12 months at the start of each: an annual charge's 12,000 credits give 1,000 a month with monthly. billingPeriod: the whole amount at the start of each billing period. Each of these allocations expires when its period ends. oneTime: amount once, when the charge starts, with no expiry. Case and punctuation are ignored (semi-annually works); any other value counts as monthly.

values
monthlyquarterlysemiAnnuallyannualbillingPeriodoneTime
creditGrantTiming
Type: "on_invoice_posted" or "on_payment" or nullenum

When each allocation's credits are released. Null: at the start of its period. on_invoice_posted: once the order's invoice for the period (the first invoice to bill it) is posted. on_payment: once that invoice is paid. A later invoice that adjusts the period, such as a proration or a correction, neither releases nor voids them. Until then the allocation is pending, even past the end of its period: usage may draw on it, but that usage is held, and becomes overage if the invoice is voided (or, for an invoice Stripe collects, voided or marked uncollectible in Stripe). A charge with no price releases its credits at the start of the period.
creditsCurrencyId
Type: string | null

The credits currency (cc_…) the credits are in; null for your default credits currency.
id
Type: string

Identifies the benefit. Generated (a UUID) when you leave it out.
isInfiniteTotal
Type: boolean

Unlimited credits: amount is ignored and no overage is billed.
overageUnitPrice
Type: number | null
min:
0

Price of each credit used beyond the customer's credits, in minor units (cents for USD) of the order's currency. Fractions are allowed.
overageUnitPrices
Type: object | null

Overage price per credit by currency (ISO 4217 code to minor units). Overrides overageUnitPrice in that currency.

Properties: 1
recipient
Type: "organization" or "seat"enum

organization: one pool for the whole customer, which every signal can use. seat: each of the charge's seats gets amount credits of its own, used only by signals that name the seat's user (data.external_user_id), before the shared pool. Use seat on seat-based charges.
rolloverAmount
Type: number | null
min:
0

The most unused credits that carry over, into a grant of their own, when an allocation expires. Null with a rolloverDuration: all unused credits carry over. With neither set, none do. Rolled-over credits don't roll over again.
rolloverDuration
Type: number | null
min:
0

How long rolled-over credits last, in rolloverDurationUnits from the end of the allocation they came from. Null: one allocation period.
rolloverDurationUnit
Type: string | nullenum

The unit of rolloverDuration. Null: months.

values
daysweeksmonthsyearsnull

Examples

{
  "creditsCurrencyId": null,
  "recipient": "organization",
  "isInfiniteTotal": false,
  "allocationCadence": "monthly",
  "creditGrantTiming": null,
  "overageUnitPrice": 10,
  "overageUnitPrices": null,
  "rolloverAmount": null,
  "rolloverDuration": null,
  "rolloverDurationUnit": null,
  "id": "e2d7b9a4-6c13-4f8e-b5a0-7d91c3f28e64",
  "amount": 500
}

PricingCreditBracket

MeterFilter