Billing
In this page you will learn how an app charges the customer that installed it, and how it learns the outcome. Payment is handled by the marketplace: your app never sees a card.
Plans
Plans are defined by you in the marketplace's partner space: a recurring plan (with an interval and an optional trial) or a one-time plan, with an amount in cents, excluding VAT. List the plans of your app:
curl https://{tenant}-api.example.com/api/app/v1/billing/plans \
-H "Authorization: Bearer <access_token>"
Subscribe or charge
Billing needs no scope: the installation is the one of your token, never of the request.
| Operation | Does |
|---|---|
POST /api/app/v1/billing/subscriptions | Asks for a subscription to a plan. Answers 201 with the subscription id, its status and a confirmationUrl |
GET /api/app/v1/billing/subscriptions/current | The live subscription of the installation, or 404 |
POST /api/app/v1/billing/subscriptions/current/cancel | Cancels at the end of the paid period. Answers 202 |
POST /api/app/v1/billing/charges | Asks for a one-time charge. Answers 201 with a confirmationUrl |
GET /api/app/v1/billing/charges/{id} | A charge of this installation |
The body of a request is { "planId": "...", "returnUrl": "https://..." }, at most 8 KB. The returnUrl must be https, without credentials or fragment, on the origin of your app_url or of one of your redirect_urls.
Confirmation
Nothing is charged until a person confirms. Send an administrator of the platform to the confirmationUrl: they see the plan and the price, then approve or decline, and the platform brings them back to your returnUrl. The confirmationUrl is built by the platform from the sale id: you cannot choose it.
Know the outcome
You are told through two webhooks that need no scope:
app_subscription/updated, on every change of status of the subscription;app_charge/updated, on every change of status of a charge.
The status is the marketplace's. Read the current state with the operations above whenever you need it, for instance when a user opens your app.
Access is yours to decide
The platform does not freeze an unpaid app. Your app enforces its own access from the subscription status: for example full access while trialing or active, a grace period when past_due, and read-only or no access after canceled and once the paid period has ended (currentPeriodEnd).
Limits
The billing operations are limited to 30 requests a minute per installation, on top of the App API limit.