Skip to main content

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.

OperationDoes
POST /api/app/v1/billing/subscriptionsAsks for a subscription to a plan. Answers 201 with the subscription id, its status and a confirmationUrl
GET /api/app/v1/billing/subscriptions/currentThe live subscription of the installation, or 404
POST /api/app/v1/billing/subscriptions/current/cancelCancels at the end of the paid period. Answers 202
POST /api/app/v1/billing/chargesAsks 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.