Skip to content

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

Responses
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

Responses
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

Responses
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.

Responses
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.

Responses
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.

Responses
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

Responses
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

Responses
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.

Responses
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