KintsugiKintsugi

Update the organization's subscription plan

PATCH/billing/plan

Moves the existing billing subscription of the org selected by Organization-Id, Connection-Id, or Entity-Id to the given plan. Requires a subscription to already exist; use POST /billing/checkout for a first-time checkout. Answers 400 when the organization's current plan cannot move to the requested plan. Requires an owner or admin of the organization, or the organization's own API key.

Authorization

Api-KeystringRequired

Your secret API key. Include it with every request.

Headers

Api-Versiondate

Release date, as YYYY-MM-DD. Defaults to 2026-07-21.

Organization-Idstring

Target organization id (Organization-Id selector).

Connection-Idstring

Target connection id; resolves to its organization.

Entity-Idstring

Platform entity id; resolves to a connection's organization.

Entity-Sourcestring

Optional source to disambiguate an Entity-Id.

Body

billingPlanPublicBillingWritePlanEnumRequired

Plan tier to update the existing subscription to.

Available options:GROWTHPREMIUM

Response

idstringRequired

Billing subscription id.

statusPublicSubscriptionStatusEnumRequired

Subscription status.

Available options:FUTUREIN_TRIALACTIVENON_RENEWINGPAUSEDCANCELLEDTRANSFERRED
currencyPublicCurrencyEnumRequired

ISO-4217 currency for all amounts.

Available options:AEDAFNALLAMDANGAOAARSAUDAWGAZNBAMBBDBDTBGNBHDBIFBMDBNDBOBBRLBSDBTNBWPBYNBZDCADCDFCHFCLPCNYCOPCRCCUCCUPCVECZKDJFDKKDOPDZDEGPERNETBEURFJDFKPGBPGELGGPGHSGIPGMDGNFGTQGYDHKDHNLHRKHTGHUFIDRILSIMPINRIQDIRRISKJEPJMDJODJPYKESKGSKHRKMFKPWKRWKWDKYDKZTLAKLBPLKRLRDLSLLYDMADMDLMGAMKDMMKMNTMOPMRUMURMVRMWKMXNMYRMZNNADNGNNIONOKNPRNZDOMRPABPENPGKPHPPKRPLNPYGQARRONRSDRUBRWFSARSBDSCRSDGSEKSGDSHPSLLSOSSPLSRDSTNSVCSYPSZLTHBTJSTMTTNDTOPTRYTTDTVDTWDTZSUAHUGXUSDUYUUZSVEFVNDVUVWSTXAFXCDXDRXOFXPFYERZARZMWZWD
billingPeriodintegerRequired

Length of one billing cycle.

billingPeriodUnitstringRequired

Unit for billingPeriod, e.g. month or year.

currentTermStartstring

Start of the current billing term.

currentTermEndstring

End of the current billing term.

nextBillingAtstring

When the next invoice is expected.

couponstring

Coupon code applied to the subscription, if any.

itemsSubscriptionItem[]Required

Priced lines on the subscription.

200

Successful Response

400

The request was invalid.

401

Authentication failed or was missing.

403

The credential is not permitted for this request.

404

The requested resource was not found.

422

Validation Error

503

A service this request depends on was unavailable. Retry the request.

cURL
PATCH /billing/plan
-H "Api-Key: ***"
-H "Api-Version: 2026-07-21"
{
"billingPlan": "GROWTH"
}
Response
{
"id": "3f6c2b1e-8a4d-4c2e-9b1f-2d7e5a6c9f10",
"status": "FUTURE",
"currency": "AED",
"billingPeriod": 1,
"billingPeriodUnit": "billing period unit",
"currentTermStart": "2026-07-28T12:00:00Z",
"currentTermEnd": "2026-07-28T12:00:00Z",
"nextBillingAt": "2026-07-28T12:00:00Z",
"coupon": "coupon",
"items": [
{
"itemPriceId": "3f6c2b1e-8a4d-4c2e-9b1f-2d7e5a6c9f10",
"itemType": "item type",
"quantity": 2,
"unitPrice": "10.00",
"amount": "10.00"
}
]
}
Update the organization's subscription plan (2026-07-21) | Kintsugi API Reference