# Billing

> How an app sells itself: plans, a subscription or a one-time charge, the customer's confirmation, and the webhooks that tell you the status.

Source: https://developers-staging.foodpilot.tech/build/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:

```bash
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](/build/webhooks/topics) 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](/build/app-api).
