SynqDocs
Management APIOrgs

Preview a plan change

What moving the org to a plan would do, changing nothing: which step it takes (`action`), what it costs today (an upgrade prorated by Stripe), when it applies, the features it gains and loses, its limits before and after, and what the org has above the new limits. Needs `org.billing.view`, so a member who can't change the plan can see what to ask for.

POST/v1/orgs/{org}/billing/plan/preview

What moving the org to a plan would do, changing nothing: which step it takes (action), what it costs today (an upgrade prorated by Stripe), when it applies, the features it gains and loses, its limits before and after, and what the org has above the new limits. Needs org.billing.view, so a member who can't change the plan can see what to ask for.

Authorization

bearer
AuthorizationBearer <token>

An org API key (sk_live_…, sk_test_…), or an access token from the Synq issuer (the synq brand, on the accounts host) for this API.

In: header

Path Parameters

org*string

The org's id

Match^org_[0-9a-hjkmnp-tv-z]{26}$

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://api.synq.build/v1/orgs/org_01h455vb4pex5vsknk084sn02q/billing/plan/preview" \  -H "Authorization: Bearer $SYNQ_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "plan": "scale",    "interval": "month"  }'
{  "action": "upgrade",  "plan": "scale",  "interval": "month",  "currency": "usd",  "amount_due_today_cents": "17500",  "price_cents": "20000",  "trial_days": 14,  "applies": "now",  "at": "2026-10-21T12:00:00.000Z",  "gains": [    "auth.byo_connections"  ],  "loses": [    "auth.byo_connections"  ],  "quotas": {    "apps": {      "from": 0,      "to": 0    },    "brands": {      "from": 0,      "to": 0    },    "monthly_active_users": {      "from": 0,      "to": 0    },    "audit_retention_days": {      "from": 0,      "to": 0    }  },  "over_limits": [    {      "quota": "apps",      "count": 0,      "limit": 0    }  ]}

Start checkout for a plan POST

Stripe Checkout for one of the plans sold (`GET /v1/plans`), billed monthly or yearly, with the plan's overage for monthly active users above the allowance as a metered item; promotion codes are taken. Send the person to `url`; once they've paid, Stripe's webhook moves the org to the plan, moments later. An org that pays for a plan already changes it in the billing portal instead. A paid or contract plan assigned by Synq staff without a subscription must be changed by staff (`conflict`). Needs `org.billing.edit`.

Change a paying org's plan POST

Moves an org that pays for a plan to another plan or cadence. An upgrade (a dearer plan, or monthly to yearly) applies at once: Stripe prorates it and invoices the difference now, on the card it has. A declined card is `payment_failed`, and nothing changes. When the person's bank wants to confirm the payment (3-D Secure) it is `payment_requires_action`: nothing is charged and nothing changes yet, `hosted_invoice_url` is Stripe's page where they confirm it, and once they do Stripe takes the payment and the upgrade applies, as Stripe's webhook tells Synq (with the email and `org.plan_changed`, by whoever asked); it waits a day at most (`expires_at`), and `GET …/billing` says it meanwhile. Any other change, the plan the org is on included, calls off a payment still waiting. While the plan is set to end, an upgrade that waits for the bank is refused (`conflict`): renew the plan first, then upgrade. A downgrade (a cheaper plan, or yearly to monthly) applies at the end of the period paid for. On a trial nothing has been paid, so nothing is prorated: an upgrade changes the plan the trial is of, and a downgrade waits for the trial's last day, the trial carrying on until then. The free plan ends the paid one at the end of its period (a trial's last day), as cancelling in the billing portal does, and calls off a downgrade waiting for then (`called_off_change` in `GET …/billing`). A paid plan chosen while the plan is set to end calls the end off. The plan the org is on, at its cadence, keeps it: it renews a plan set to end, bringing back a downgrade that end called off, as renewing in the portal does, or calls off a waiting downgrade. The org's owners and admins get an email for each change: the plan, its price and the day. The org's plan follows Stripe's webhook, moments after. Needs `org.billing.edit`.