API reference: billing
The Orbit subscription, through Stripe: plan prices, Checkout and billing portal sessions, cancelling at the end of the paid period, and Stripe’s webhook. Or through the App Store: the transactions the Apple app records, and Apple’s server notifications.
POST /v1/billing/app-store-notifications
Receives App Store Server Notifications, version 2, signature-verified and idempotent. Needs no session.
Each notification is processed once, by its notificationUUID: a redelivery is answered 200 and changes nothing, and one signed more than ten days ago is refused. Whatever its type, the transaction and renewal info it carries are recorded as the subscription now stands, unless the server holds later ones. Apple’s TEST notification changes nothing.
Request body, application/json: AppStoreNotification
| Status | Description | Body |
|---|---|---|
| 200 | Notification processed, now or before | |
| 400 | Not the App Store’s, or stale | Problem application/problem+json |
| 413 | The body is too large | Problem application/problem+json |
| 415 | The body is not JSON | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | App Store purchases unavailable | Problem application/problem+json |
POST /v1/billing/app-store-transactions
Records a transaction the app received from `StoreKit`, after a purchase or a restore. Needs a session.
The transaction must be the App Store’s, for this app and the environment this server accepts, and its appAccountToken must be the caller’s account id, which the app sets at purchase. Orbit then holds until the period ends, and Apple’s notifications renew it. A transaction the server already holds, or an older one, changes nothing.
Request body, application/json: AppStoreTransaction
| Status | Description | Body |
|---|---|---|
| 200 | The account, in Orbit through the App Store. | Account application/json |
| 400 | Not the App Store’s signed data for this app | Problem application/problem+json |
| 401 | No valid session token | Problem application/problem+json |
| 403 | The purchase is another account’s, or a sandbox one past the account’s week | Problem application/problem+json |
| 409 | The subscription ended or was refunded | Problem application/problem+json |
| 413 | The body is too large | Problem application/problem+json |
| 415 | The body is not JSON | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | App Store purchases unavailable | Problem application/problem+json |
POST /v1/billing/checkout-sessions
Starts a Stripe Checkout session for the chosen plan, which the payment dialog completes with Stripe.js. Needs a session.
Request body, application/json: CheckoutRequest
| Status | Description | Body |
|---|---|---|
| 201 | The session, for Stripe.js. | CheckoutSession application/json |
| 400 | The request is malformed | Problem application/problem+json |
| 401 | No valid session token | Problem application/problem+json |
| 409 | Subscription already active | Problem application/problem+json |
| 413 | The body is too large | Problem application/problem+json |
| 415 | The body is not JSON | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | Billing unavailable | Problem application/problem+json |
POST /v1/billing/portal-sessions
Opens the Stripe customer portal for subscription self-service. Needs a session.
| Status | Description | Body |
|---|---|---|
| 201 | Portal URL. | UrlResponse application/json |
| 400 | No billing profile | Problem application/problem+json |
| 401 | No valid session token | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | Billing unavailable | Problem application/problem+json |
GET /v1/billing/prices
Lists the plan prices in every currency. Needs no session.
Cached from Stripe, so a displayed price never drifts from the charge. Public. Unconfigured billing yields an empty catalogue.
| Status | Description | Body |
|---|---|---|
| 200 | Plan prices per currency. | PriceList application/json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |
GET /v1/billing/subscription
Returns the caller's subscription as last mirrored from Stripe: status `none` without one. Needs a session.
| Status | Description | Body |
|---|---|---|
| 200 | The subscription as last mirrored from Stripe. | SubscriptionInfo application/json |
| 401 | No valid session token | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | The service is at capacity | Problem application/problem+json |
PATCH /v1/billing/subscription
Schedules or clears end-of-period cancellation of the live subscription. Needs a session.
A JSON Merge Patch. Access stays until currentPeriodEnd. An account in Orbit by an
operator’s grant has no subscription, so there is none here to change.
Request body, application/merge-patch+json: SubscriptionUpdate
| Status | Description | Body |
|---|---|---|
| 200 | The subscription as Stripe now holds it. | SubscriptionInfo application/json |
| 400 | The request is malformed | Problem application/problem+json |
| 401 | No valid session token | Problem application/problem+json |
| 404 | No live subscription | Problem application/problem+json |
| 413 | The body is too large | Problem application/problem+json |
| 415 | The body is not a JSON Merge Patch | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | Billing unavailable | Problem application/problem+json |
POST /v1/billing/webhook
Receives Stripe webhooks, signature-verified and idempotent. Needs no session.
An event says that a subscription changed, never what it is now: events arrive in any order, so the subscription is read from Stripe when one is processed.
Request body, application/json: object
| Status | Description | Body |
|---|---|---|
| 200 | Event processed | |
| 400 | Invalid signature | Problem application/problem+json |
| 413 | The body is too large | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | Billing unavailable | Problem application/problem+json |
POST /v1/billing/withdrawals
Withdraws from Orbit within 14 days of its start: refunds its payment in full, ends it at once, and acknowledges it by email with the moment it was received. Needs a session.
The refund comes first and the cancellation after, each keyed by the subscription, so a retry after a failure between them refunds once and still ends it.
| Status | Description | Body |
|---|---|---|
| 201 | Withdrawn, refunded and acknowledged. | Withdrawal application/json |
| 401 | No valid session token | Problem application/problem+json |
| 404 | No live subscription | Problem application/problem+json |
| 409 | The 14 days have passed | Problem application/problem+json |
| 429 | Too many requests | Problem application/problem+json |
| 500 | The service failed | Problem application/problem+json |
| 503 | Billing unavailable | Problem application/problem+json |