Sell a plan
In this tutorial you will add a "Subscribe" button to your embedded page. The administrator confirms the price in the platform, comes back to your app, and your app unlocks its features. The rules of billing are in Billing.
1. Define the plan
Create the plan in the partner space: recurring (with an interval and an optional trial) or one-time, with an amount in cents, excluding VAT. Subscribe to the billing topics in your manifest:
{
"webhooks": [
{ "topic": "app_subscription/updated", "uri": "https://app.example.com/webhooks" },
{ "topic": "app_charge/updated", "uri": "https://app.example.com/webhooks" }
]
}
2. Ask for the subscription from your server
The page never holds the access token: it asks your server, which calls the platform. Because this request changes something, accept each session token once, by its jti:
app.post('/api/billing/subscriptions', express.json({ limit: '4kb' }), async (request, response) => {
const session = await authenticate(request, response); // verifies the session token, as in the product tab tutorial
if (!session) return;
if (!(await tokens.claimOnce(session.claims.jti))) return response.status(401).json({ error: 'token_replayed' });
const subscription = await appApi(session.installation, '/api/app/v1/billing/subscriptions', {
method: 'POST',
body: { planId: request.body.planId, returnUrl: 'https://app.example.com/app' },
});
response.status(201).json(subscription); // holds the confirmationUrl
});
The returnUrl must be on the origin of your app_url or of a redirect URL.
3. Send the administrator to confirm
The confirmationUrl is a page of the platform. From your embedded page, go there with App Bridge:
const created = await fetch('/api/billing/subscriptions', {
method: 'POST',
headers: { Authorization: `Bearer ${await app.getSessionToken()}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ planId }),
}).then((r) => r.json());
await app.navigate.foodpilot(new URL(created.confirmationUrl).pathname);
The administrator sees the plan and the price, approves or declines, and comes back to your returnUrl. Nothing is charged until they approve.
4. Unlock from the status
When app_subscription/updated arrives, store its status. When a user opens your app, read the current one:
const subscription = await appApi(installation, '/api/app/v1/billing/subscriptions/current'); // 404: none
const paid = ['trialing', 'active'].includes(subscription?.status);
The platform does not lock an unpaid app: your app decides, for example with a grace period on past_due.
5. Let them cancel
POST /api/app/v1/billing/subscriptions/current/cancel ends the subscription at the end of the paid period. Accept the session token once here too.