SynqDocs
Management APIOrgs

Start a plan's trial

Puts the org on a plan that has trial days (`GET /v1/plans`, `trial_days`) for that many days, free and with no card. Add a card in the billing portal before it ends (`flow: payment_method_update`) to carry on; without one the org moves to the free plan on the last day, and sign-in never stops. An org gets one trial; after it, start the plan with checkout. A paid or contract plan assigned by Synq staff without a subscription must be changed by staff. The org is on the plan when this returns. Needs `org.billing.edit`.

POST/v1/orgs/{org}/billing/trial

Puts the org on a plan that has trial days (GET /v1/plans, trial_days) for that many days, free and with no card. Add a card in the billing portal before it ends (flow: payment_method_update) to carry on; without one the org moves to the free plan on the last day, and sign-in never stops. An org gets one trial; after it, start the plan with checkout. A paid or contract plan assigned by Synq staff without a subscription must be changed by staff. The org is on the plan when this returns. Needs org.billing.edit.

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

application/problem+json

application/problem+json

curl -X POST "https://api.synq.build/v1/orgs/org_01h455vb4pex5vsknk084sn02q/billing/trial" \  -H "Authorization: Bearer $SYNQ_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "plan": "pro",    "interval": "month"  }'
{  "plan": "pro",  "interval": "month",  "trial_ends_at": "2026-11-04T16:00:00.000Z"}

End the trial now and pay POST

Ends the org's trial now and pays for its plan: Stripe charges the first period's invoice today on the card it has (nothing prorated), the billing date moves to today, and the plan carries on, charged a period from now; users over the allowance are billed at the period's end, as ever. Answers Stripe's paid invoice, whose `hosted_invoice_url` is the receipt. A declined card is `payment_failed`, nothing is charged, and the trial carries on. When the person's bank wants to confirm the payment (3-D Secure) it is `payment_requires_action`: nothing is charged yet and the trial carries on, `hosted_invoice_url` is Stripe's page where they confirm it, and once they do Stripe takes the payment and the trial ends, as Stripe's webhook tells Synq (with the email and the audit row); it waits a day at most (`expires_at`). Refused while the trial is set to end (renew the plan first, `POST …/billing/plan` with the plan the org is on) and while a move down waits for its end (call the move off the same way, then end the trial; or keep the move and pay when the trial ends): `conflict`. Without a card it is `card_required`, and with no trial `no_trial`. `POST …/billing/trial/end/preview` says what it charges first. The owners and admins get an email of it. Recorded as `org.trial_ended`. Needs `org.billing.edit`.

Leave an org POST

For a person, not an API key; the owner hands the org over first. Their access to the org ends at once, as removing them ends it (`DELETE …/members/{user}`). Needs `org.read`, which every member has. Recorded as `member.left`.