Skip to content

Change seats or the period

PATCH
/v1/billing/subscription
curl --request PATCH \
--url https://beta-api.plune.ai/v1/billing/subscription \
--header 'Content-Type: application/json' \
--cookie plune_session=<plune_session> \
--data '{ "seats": 5 }'

More seats take effect at once: a grant with them to the paid end, and seats added × the seat’s dollar price × days left ÷ days in the period is added to the next charge, at that charge’s rate (ADR 0081 §3). Fewer seats and another period take effect from the next period (nextSeats, nextPeriod). Paddle: its own proration, to the minute, billed with the next payment; fewer seats are billed nothing now (do_not_bill); a month↔year switch answers 501 not_built_for_provider. Paddle is asked first: a refusal changes nothing of ours. The session alone, the owner’s alone for a company. Ten calls a minute.

companyId
string

Team: a company the caller owns. Absent: the caller’s own account (Personal).

Media type application/json
object
>= 1 properties
seats

Team: 3 to 50; Personal: 1

integer
>= 1 <= 50
period
string
Allowed values: month year
Examples

Two more seats now

{
"seats": 5
}

The subscription as changed

Media type application/json
object
subscription
required
object
id
required
string
provider
required
string
Allowed values: paddle monopay liqpay
tier
required
string
Allowed values: personal team
period
required
string
Allowed values: month year
seats
required
integer
>= 1
status
required
string
Allowed values: active cancelling ended
paidUntil
required
string | null format: date-time
nextPeriod
required

Another period, from the next one

string | null
Allowed values: month year
nextSeats
required

Fewer seats, from the next period

integer | null
>= 1
extraUsdCents
required

Seats added mid-period: owed on top of the next charge, in US cents (0 when nothing)

integer
cancelledAt
required

When the owner cancelled at the period’s end

string | null format: date-time
failedAt
required

The latest failed renewal payment not followed by a payment (Monopay: of an invoice still unpaid; Paddle: transaction.payment_failed)

string | null format: date-time
refund
required

A refund that ended it: Free limits at once

object
at
required
string format: date-time
payUrl
required

Monopay: the link to pay for the next period, while it lives

string | null format: uri
receiptUrl
required

Where the receipt is: Paddle’s customer portal page of the subscription (its past payments), for the owner; a short-lived link, never stored; null when the provider gives none

string | null format: uri
manageUrl
required

Where the card is changed: Paddle’s customer portal with the payment method form open, for the owner; a short-lived link, never stored; null when the provider gives none

string | null format: uri
Example
{
"subscription": {
"provider": "paddle",
"tier": "personal",
"period": "month",
"status": "active",
"nextPeriod": "month"
}
}

Not JSON, nothing named, or a seat count out of range

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

No / invalid session

An API token (session_required), or a member of the company who is not its owner (owner_only)

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

A company the caller is not in

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

No active subscription whose period has not passed (nothing_to_change), or it changed meanwhile (conflict)

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

Rate-limited: the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442; the body names the plan, #2092). Retry-After carries the seconds until the window rolls over.

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}
Retry-After
integer

Seconds until the window rolls over

A month↔year switch through Paddle is not built yet (not_built_for_provider)

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

The payment provider refused the change (provider_error); nothing of ours changed

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

The provider’s variables are not set on this server (provider_not_configured), or it could not be reached (provider_unreachable) - try again

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}