Billing

Swap the plan and/or billing interval on a paid subscription

Commitment increases (tier upgrade, monthly→annual) prorate and invoice immediately. Commitment decreases are deferred to the next renewal so the prepaid term is honoured: a tier downgrade keeps the higher tier until then (after a blocking over-quota check — 402 PLAN_DOWNGRADE_BLOCKED if over limits), and a pure annual→monthly switch keeps the annual term. Omitting the interval keeps the current cadence.

post/billing/subscription/plan

Request

  • Base URL: https://api.nippy.host
  • URL: https://api.nippy.host/billing/subscription/plan
  • Auth: bearer (a scheme the document does not define)

Request body

plan'basic' | 'pro' | 'max' required

Target paid plan (free is not a selectable target here)

interval'month' | 'year'

Billing interval; defaults to monthly when omitted

currency'usd' | 'gbp' | 'eur' | 'chf'

Explicit presentment currency for Checkout. Omit to auto-detect from the customer location (USD fallback). Ignored on plan swaps — a subscription currency is locked at creation.

Response

plan'free' | 'basic' | 'pro' | 'max' required
status'active' | 'trialing' | 'past_due' | 'canceled' | 'incomplete' | 'incomplete_expired' | 'unpaid' | 'paused' required

Stripe-mirrored status (free tier is always active)

seatsnumber required

Seats billed this period (item quantity)

interval'month' | 'year' required

Current billing cadence (monthly/annual)

currency'gbp' | 'usd' | 'eur' | 'chf' required

Presentment currency of the paid subscription (locked at creation). Drives price display; cosmetic on the free tier.

perSeatPencenumber required

Per-seat recurring charge in currency minor units at the subscription's cadence — what the account actually pays. Can differ from the catalog figure when the subscription is grandfathered on an older pricing version. 0 on the free tier.

scheduledInterval'month' | 'year' nullable required

A cadence queued to apply at the next renewal (annual→monthly), else null

scheduledPlan'free' | 'basic' | 'pro' | 'max' nullable required

A lower tier queued to apply at the next renewal (downgrade), else null

currentPeriodEndstring date-time nullable required
cancelAtPeriodEndboolean required

Whether the subscription ends at period close

trialModalPendingboolean required

Whether the one-time upgrade offer is still unanswered on this account (ADR 0053; named for the trial it offered until ADR 0063). Only says it has not been answered — whether it is due (a free personal account with a site, viewed by its owner) is the client’s call.

accountCreatedAtstring date-time required

When the account was created. The one-time upgrade offer reads it to tell a first session from a return visit (ADR 0053, amendment 1) — a fact from the server, because a browser-local flag fails on a second device.

duplicateHoldboolean required

True while the account is on a duplicate-account hold (ADR 0057): its live sites are offline and it cannot publish or start a plan until its owner answers the request at /duplicate-accounts.

Changes

No recorded changes to this operation across all 1 revision of this API.