Billing
The account’s subscription, from Koo’s mirror of Stripe
Owner-only: it exposes invoices and the card’s brand/last4. Returns 404 while the account is on Free. The `invoices` list is empty until the billing webhook mirrors them.
curl https://api.koo.io/accounts/:accountId/subscription \ -H "Authorization: Bearer kc_your_api_token"{ "id": "acct_01example0000000000000000x", "accountId": "acct_01example0000000000000000x", "status": "active", "cadence": "monthly", "currentPeriodEnd": "2026-01-01T00:00:00.000Z", "cancelAtPeriodEnd": true, "priceVersion": "example", "legacyUntil": "2026-01-01T00:00:00.000Z", "couponCode": "example", "coupon": { "code": "example", "label": "example", "percentOff": 1, "amountOffCents": 0 }, "items": [ { "kind": "plan", "ref": "example", "quantity": 0, "unitPriceUsd": 0 } ], "invoices": [ { "id": "acct_01example0000000000000000x", "periodStart": "2026-01-01T00:00:00.000Z", "periodEnd": "2026-01-01T00:00:00.000Z", "totalUsd": 0, "kind": "subscription", "status": "example", "pdfUrl": "https://example.com", "hostedUrl": "https://example.com" } ], "paymentMethod": { "brand": "example", "last4": "example", "expMonth": 1, "expYear": 1 }}Subscribe to a paid plan — returns a Stripe Checkout URL
Prices the SUBSCRIPTION as it stands today (plan fee + extra seats) and opens a hosted Stripe Checkout session. Compute — the resources your services run — is not part of Checkout: it bills monthly in arrears for what you actually ran, minus the always-free allowance and your plan credit. **The tier does not change here.** It flips only when Stripe confirms the subscription through the billing webhook, so a client must never show the new plan on this response. Idempotent: a second call reuses the account’s Stripe customer, and a call while a subscription already exists returns 409. `monthly` and `annual` cadences are supported.
Target tier id — must be a self-serve tier (never `enterprise`).
Billing interval. `annual` bills a year of plan + seats up front at the tier’s 10× price (the commitment discount). Compute always bills monthly in arrears for what you ran, either way.
Redirect the browser here to complete payment.
curl https://api.koo.io/accounts/:accountId/subscription \ -X POST \ -H "Authorization: Bearer kc_your_api_token" \ -H "Content-Type: application/json" \ -d '{ "tierId": "tier_01example0000000000000000x" }'{ "checkoutUrl": "https://example.com"}Cancel the subscription, with the refund the cadence has earned
Owner-only. **Monthly**: the subscription lapses at the end of the period already paid for, with no refund — `accessUntil` is that date. **Annual**: the subscription ends immediately and the unused months are refunded in cash, clawing back the commitment discount (you pay the regular monthly rate for the time you used). A very young annual subscription is cancelled but its refund is held for staff review. The tier reverts to Free when Stripe confirms the cancellation through the billing webhook.
Present only when cash was actually refunded.
curl https://api.koo.io/accounts/:accountId/subscription \ -X DELETE \ -H "Authorization: Bearer kc_your_api_token"{ "status": "canceled", "accessUntil": "2026-01-01T00:00:00.000Z", "refund": { "amountUsd": 0, "currency": "USD", "estimatedArrivalDays": 0 }, "refundUnderReview": true}The account’s compute bill so far this period
Owner-only. Rates the usage ledger LIVE — gross compute accrued this period, the in-kind free allowance applied per service type, the plan’s monthly compute credit (a projection mid-period; Stripe applies it at invoice finalization), and the resulting net charged in arrears at month end. Works for EVERY account including Free (it never 404s); a Free account, or a paid one whose compute item is not yet attached, reports against the current UTC calendar month as a display window. `netUsd` of $0 is a normal answer.
applied/remaining are as-of-asOf projections; the credit is applied at invoice finalization.
curl https://api.koo.io/accounts/:accountId/compute-usage \ -H "Authorization: Bearer kc_your_api_token"{ "periodStart": "2026-01-01T00:00:00.000Z", "periodEnd": "2026-01-01T00:00:00.000Z", "asOf": "2026-01-01T00:00:00.000Z", "accruedUsd": 0, "allowance": { "eligible": true, "appliedUsd": 0, "byType": { "key": { "appliedUsd": 0, "coveredServiceId": "coveredservice_01example0000000000000000x" } } }, "credit": { "includedUsd": 0, "appliedUsd": 0, "remainingUsd": 0 }, "netUsd": 0, "projectedNetUsd": 0, "services": [ { "serviceId": "svc_01example0000000000000000x", "serviceName": "example", "projectName": "example", "type": "web", "accruedUsd": 0, "allowanceAppliedUsd": 0 } ]}The promo code saved for the account’s next checkout
Owner-only. `pending` is the code redeemed while the account has no paid subscription — it is spent at the next Checkout, not now. It reads `null` once the code has moved onto the subscription (it shows on `GET /accounts/{accountId}/subscription` from then on), and `null` when nothing is saved. Never 404s.
curl https://api.koo.io/accounts/:accountId/coupon \ -H "Authorization: Bearer kc_your_api_token"{ "pending": { "code": "example", "label": "example", "percentOff": 1, "amountOffCents": 0 }}Redeem a promo code — applied to a live subscription, or saved for the next checkout
Owner-only. With a paid subscription the discount comes off the next invoice and survives service changes and reprices. **Without one the code is SAVED on the account** and spent the moment you subscribe — read it back from `GET /accounts/{accountId}/coupon`. An unknown code answers 404; an expired one, a code that has hit its redemption limit, or one restricted to another plan answers 422.
curl https://api.koo.io/accounts/:accountId/coupon \ -X POST \ -H "Authorization: Bearer kc_your_api_token" \ -H "Content-Type: application/json" \ -d '{ "code": "example" }'Remove the promo code — the applied one, or the one saved for checkout
Owner-only. The next invoice bills the full amount; a code saved for checkout is simply dropped. Idempotent: with nothing applied and nothing saved this is a no-op, not a 404.
curl https://api.koo.io/accounts/:accountId/coupon \ -X DELETE \ -H "Authorization: Bearer kc_your_api_token"A Stripe Customer Portal session — manage card, invoices, cancellation
Open this to manage payment methods, invoices and cancellation.
curl https://api.koo.io/accounts/:accountId/billing-portal \ -H "Authorization: Bearer kc_your_api_token"{ "url": "https://example.com"}