v20

latestOpenAPI 3.0.0raw.githubusercontent.com2026-07-214885191.3 KB

Plans

Create a plan for a product

Creates a plan under the product. Unfinished pricing fields (setup fee, trial days, rollover, tiers, etc.) are stripped from SDK input, and unsupported plan types fall back to "recurring".

post/v1/sdk/products/{productRef}/plans

Path parameters

productRefstring required

Example:prd_1A2B3C4D

Product reference or ID

Request body

accessExpiryDaysinteger

autoRenewboolean

basePricenumber

billingCycle'weekly' | 'monthly' | 'quarterly' | 'yearly' | 'custom'

billingModel'pre-paid' | 'post-paid'

cancellationNoticeDaysinteger

creditsPerUnitinteger

currencystring

defaultboolean

descriptionstring

featuresobject required

freeUnitsinteger

hiddenboolean

limitinteger

limitsobject required

maxActiveUsersinteger

metadataobject required

namestring required

pricenumber

rolloverUnusedUnitsboolean

setupFeenumber

status'active' | 'inactive' | 'archived'

taxBehavior'auto' | 'inclusive' | 'exclusive'

trialDaysinteger

type'recurring' | 'usage-based' | 'one-time' | 'hybrid'

Response

Plan created successfully

accessExpiryDaysnumber

Access expiry in days

billingCyclestring

Billing cycle

billingModel'pre-paid' | 'post-paid'

Billing model

createdAtstring required

Creation timestamp

creditsPerUnitnumber

Credits per usage unit (integer, >= 1)

currencystring required

Currency code (ISO 4217)

currencySymbolstring

Currency symbol (derived from currency)

descriptionstring

Plan description

featuresobject

Plan features

freeUnitsnumber

Number of free units included

hiddenboolean required

Whether the plan is hidden from customer-facing surfaces. When true, the plan does not appear in checkout or the SDK catalog and can only be granted via direct assignment (enterprise plans).

isActiveboolean required

Whether the plan is active (derived from status)

limitnumber

Usage limit for the meter

limitsobject

Usage limits

maxActiveUsersnumber

Maximum number of active users

measuresstring

What the plan measures for usage tracking

meterRefstring

Meter reference for usage-based plans

namestring

Plan name

pricenumber required

Plan price in cents

referencestring required

Plan reference

requiresPaymentboolean required

Whether payment is required

rolloverUnusedUnitsboolean

Whether unused units roll over to next period

setupFeenumber

One-time setup fee

statusstring required

Plan status

taxBehavior'auto' | 'inclusive' | 'exclusive'

Tax inclusion behavior for business checkout

trialDaysnumber

Free trial period in days

type'recurring' | 'one-time' | 'usage-based' | 'hybrid' required

Plan type exposed in SDK

updatedAtstring required

Last update timestamp

Example response

{
  "billingCycle": "monthly",
  "billingModel": "pre-paid",
  "creditsPerUnit": 1,
  "currency": "USD",
  "currencySymbol": "$",
  "description": "Best for teams getting started",
  "freeUnits": 100,
  "isActive": true,
  "limit": 10000,
  "measures": "requests",
  "meterRef": "mtr_1A2B3C4D",
  "name": "Starter",
  "price": 2999,
  "pricingOptions": [
    {
      "basePrice": 1999,
      "currency": "USD",
      "default": true,
      "price": 2999,
      "setupFee": 500
    }
  ],
  "reference": "pln_1A2B3C4D",
  "requiresPayment": true,
  "setupFee": 500,
  "status": "active",
  "trialDays": 14,
  "type": "recurring"
}