Sign in

v20

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

Update a plan for a product

Updates a plan under the product. Unfinished pricing fields are stripped from SDK input, and unsupported plan types fall back to "recurring".

put/v1/sdk/products/{productRef}/plans/{planRef}

Path parameters

productRefstring required
Example:prd_1A2B3C4D

Product reference or ID

planRefstring required
Example:pln_1A2B3C4D

Plan reference or ID

Request body

accessExpiryDaysinteger
autoRenewboolean
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
pricenumber
rolloverUnusedUnitsboolean
status'active' | 'inactive' | 'archived'
taxBehavior'auto' | 'inclusive' | 'exclusive'

Response

Plan updated 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"
}