Create checkout session

POSThttps://app.speybooks.com/api/v1/billing/checkout

Creates a Stripe Checkout session for the requested plan and returns the hosted Checkout URL for client-side redirect, plus the session ID for tracking. If the organisation has no Stripe customer, one is created and persisted before the session is opened.

Trial entitlement is decided through a single entry point: a first subscription receives the full trial (90 days while founder seats remain, 30 thereafter), and an organisation that has subscribed before receives no trial and goes straight to billing. The entitlement is a replacement value, never a remaining-days calculation.

Emits a billing.checkout_started audit event.

Body parameters

planstringrequired

Plan to subscribe to.

sole_traderlimited_company

Response

200Returns a Stripe Checkout URL. Redirect the user to this URL to collect payment details.

Show response fields

checkoutUrlstring

Stripe Checkout session URL. Redirect the user here.

sessionIdstring

Stripe Checkout session ID for reference.

Error codes

400Invalid or unavailable plan specified.

404Organisation not found.

RequestPOST/v1/billing/checkoutcurl

curl -X POST https://api.speybooks.com/v1/billing/checkout \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"plan": "limited_company"}'

Response200

{
  "success": true,
  "data": {
    "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_...",
    "sessionId": "cs_test_a1b2c3d4"
  }
}