Billing overview

Let your users pay with their Anikeen ID account. Anikeen ID shows the items, asks for missing addresses, takes the payment (card, SEPA direct debit and more), calculates VAT and writes the invoice. Your app never touches payment data.

Which way fits?

You want to sell	Use	Token	Who starts the payment
One-off purchases (digital or physical goods)	Orders	user	the user, on Anikeen ID
Something that recurs (a pass, a plan)	Subscriptions	user	the user, on Anikeen ID
Several subscriptions in one step	Checkout sessions	user or app	the user, on Anikeen ID
Usage billing from your backend, without the user online	App subscriptions	app	your app (trusted apps only)
Single items on the user's monthly bill (e.g. a shipped item)	Charges	app	your app (trusted apps only)

The flow

Most apps are third-party apps: they create an order or subscription as a draft, send the user to Anikeen ID to confirm and pay, and get the user back afterwards. A typical shop:

1. The user signs in with Anikeen ID (Sign in).
2. Your app creates the order: POST /api/v1/orders.
3. Redirect the user to the order's confirmation_url with your return_url.
4. The user confirms and pays on Anikeen ID, then comes back to return_url?status=…&order=….
5. Your app reads the order through the API – never trust the query string – and shows the result.
6. The order.completed webhook arrives; fulfil the order there.

Trusted apps can also check out directly and charge without asking the user.

Concepts

Return URLs

Every return_url (orders, subscriptions, checkout sessions, billing portal links) must have the origin – scheme, host and port – of one of your app's redirect URIs. The status in its query string (completed, pending or cancelled) is only a hint for the message you show.

Unconfirmed drafts expire

Orders and subscriptions a third-party app created, and checkout sessions, are cancelled when the user doesn't confirm them within 24 hours.

Monthly bills

Subscriptions are billed in arrears: every started period is added to the user's open monthly bill (a collective order) of your app and group. On the 1st of the month the bill is closed, invoiced and charged. Every app has its own monthly bills; a user may have one per app and group. Charges are lines on the same bill. One-off orders are charged on their own.

Groups

Most billing objects take a group: a free-form string of your app, e.g. a team or workspace ID. Use it to filter lists, to bill a team's subscriptions on their own monthly bill, and to show a team's invoices.

VAT

Anikeen ID calculates VAT from the user's billing address and the item type:

type	For	VAT in Germany
digital	Downloads, streams, services	19 %
physical	Goods you ship	19 %
physical-reduced	Goods with the reduced rate (books, event tickets, …)	7 %

EU businesses with a verified VAT ID are billed with reverse charge. Give each order item either a gross_price (VAT included, what the user pays exactly) or a price (net). Subscription prices are always net.

Withdrawal waiver for early starts

Consumers in the EU may withdraw from contracts concluded online within 14 days. If your service starts right away, send withdrawal_waiver_required: true when you create an order, subscription or checkout session: the confirmation page then asks the consumer to request the early start and acknowledge the consequences, and stores that. Business customers (a verified VAT ID) aren't asked. The objects then carry withdrawal_waiver_required, customer_type (business or consumer) and withdrawal_waiver (null or {accepted_at, text, locale, source, accepted_by}).

Trusted apps that check out directly can report a waiver they collected themselves: withdrawal_waiver: {accepted_at, text, accepted_by, locale?} when creating a subscription or on its checkout. Third-party apps get 403.

Order confirmations and invoices

Anikeen ID mails the user an order confirmation and the invoice, so you don't have to. Shipment mails can be turned off per shipment if your shop sends its own (see Shipments).