Document per-app collective orders and the order's oauth_client_id

Collective orders are kept per app on Anikeen ID now: an app's subscriptions are never billed on another app's order, even with the same group. Document oauth_client_id on orders (Order property, app orders) and how legacy orders that billed several apps appear (own lines only, invoice PDF refused with 403 invoice_includes_other_apps).
Document trials without a payment method
2026-11-04 22:59:41 +00:00 · 2026-11-04 23:02:48 +01:00 · 2026-11-04 22:44:03 +01:00 · 2026-11-04 22:11:16 +01:00 · 2026-11-04 22:09:39 +01:00 · 2026-11-04 22:05:30 +01:00
31 changed files with 2320 additions and 367 deletions
@@ -0,0 +1,64 @@
+# CLAUDE.md
+
+Guidance for Claude Code (and other contributors) working in this repository.
+
+## What this is
+
+`anikeen/id` is the public PHP client for the Anikeen ID API, shipped as a Laravel package
+(Laravel 11–13, PHP 8.2+). It covers OAuth/Socialite login, an API token guard, and the billing
+API (subscriptions, orders, checkout sessions, shipments, invoices, webhooks). This is a public
+repo published on Packagist: never commit secrets, internal hostnames or customer data.
+
+## Commands
+
+```shell
+composer install
+composer test                                   # vendor/bin/phpunit
+vendor/bin/phpunit --filter AppSubscriptionsTest
+composer docs                                   # regenerate README.md from README.stub
+```
+
+CI (`.github/workflows/tests.yml`) runs PHPUnit on PHP 8.3 and 8.4.
+
+## Layout
+
+- `src/Id/AnikeenId.php` – the API client (singleton, facade `AnikeenId`). Reads
+  `config('services.anikeen.*')`; `mode=staging` switches to the staging base URL unless
+  `base_url` is set. `request()` wraps Guzzle and returns a `Result`.
+- `src/Id/Billable.php` – trait for the app's user model; composes the `Concerns/Manages*` traits.
+  Its API caches are declared properties on purpose (undeclared ones would be treated as Eloquent
+  attributes and break `save()`). Add a new cache property there when a concern caches.
+- `src/Id/Concerns/` – one trait per API area. Traits on `AnikeenId` act as the app/client;
+  traits on `Billable` act for one user.
+- `src/Id/Resources/` – `BaseResource` (single object) and `BaseCollection` (lists, built via
+  `::builder()`). Failed requests throw `ApiException::fromResult()` (`CollectionException` for
+  lists), no response `::unreachable()`, `confirmation_required` a `ConfirmationRequiredException`.
+  All extend `ResourceException`.
+- `src/Id/Resources/App*` – "app" variants that use the app's own client-credentials token
+  (`AnikeenId::asApp()`, `Support/AppRequest`) instead of the user's token, for trusted apps.
+  They must not send any request until a method is called.
+- `src/Id/Auth/`, `Providers/AnikeenIdServiceProvider.php`, `Http/Middleware/` – the `anikeen`
+  guard driver and user provider, JWT validation (`Helpers/JwtParser.php` with the bundled
+  `oauth-public*.key`), scope middleware.
+- `src/Id/Webhooks/` – signature verification (`Webhook::constructEvent`) and `EventType`
+  constants.
+- `src/Support/Query.php` – query-string builder.
+- `generator/generate-docs.php` – reflects the public methods of `AnikeenId` and `Billable` traits
+  into the README.
+
+## Conventions
+
+- **README:** edit `README.stub`, never `README.md` directly, then run `composer docs`. The
+  `<!-- GENERATED-DOCS -->` marker is replaced with the method reference. Commit both files.
+- **New endpoints:** add a method to the matching `Concerns/Manages*` trait (or a resource class),
+  document request attributes with an `array{…}` PHPDoc shape and a short description per key,
+  and add an example to `README.stub` when it is a new feature.
+- **Tests:** extend `Anikeen\Id\Tests\TestCase` (Orchestra Testbench). No live API: queue
+  responses with `$this->respond($status, $body)` (Guzzle `MockHandler`) and assert the sent
+  requests via `$this->sent` / `$this->sentJson($i)` – method, path, `Authorization` header and
+  JSON body. The app token is faked as `app-token`.
+- **Compatibility:** this is a library used by several apps. Keep public method signatures
+  backwards compatible; add optional parameters instead of changing existing ones.
+- Code, comments, docs and commit messages in English. Commit subjects are short, imperative,
+  sentence case (e.g. "Ship orders: shipments with delivery notes"). Work happens on feature
+  branches merged via PR into `main`.
@@ -4,16 +4,23 @@
 [![Total Downloads](https://img.shields.io/packagist/dt/anikeen/id.svg?style=flat-square)](https://packagist.org/packages/anikeen/id)
 [![License](https://img.shields.io/packagist/l/anikeen/id.svg?style=flat-square)](https://packagist.org/packages/anikeen/id)

-PHP Anikeen ID API Client for Laravel 11+
+PHP Anikeen ID API Client for Laravel 12+
+
+Sign in with Anikeen ID and let your users pay with their Anikeen ID account: one-off orders,
+subscriptions and physical goods, with invoices, VAT and payment handled by Anikeen ID.

 ## Table of contents

 1. [Installation](#installation)
 2. [Configuration](#configuration)
-3. [General](#general)
-4. [Examples](#examples)
-5. [Documentation](#documentation)
-6. [Development](#Development)
+3. [Sign in with Anikeen ID](#sign-in-with-anikeen-id)
+4. [Payments](#payments)
+5. [Trusted apps](#trusted-apps)
+6. [API authentication](#api-authentication)
+7. [General](#general)
+8. [Examples](#examples)
+9. [Documentation](#documentation)
+10. [Development](#development)

 ## Installation

@@ -23,12 +30,20 @@ composer require anikeen/id

 ## Configuration

-Add environmental variables to your `.env` file:
+Register your app in Anikeen ID first. You need:
+
+- an OAuth client with your callback URL as redirect URI (e.g. `https://shop.test/auth/callback`),
+- a webhook endpoint (e.g. `https://shop.test/webhooks/anikeen`) if you sell something; Anikeen ID
+  shows its signing secret `whsec_…`,
+- optionally a logo, shown to your users on the login and confirmation pages.
+
+Add the credentials to your `.env` file:

 ```
 ANIKEEN_ID_KEY=
 ANIKEEN_ID_SECRET=
 ANIKEEN_ID_CALLBACK_URL=http://localhost/auth/callback
+ANIKEEN_ID_WEBHOOK_SECRET=
 ```

 To switch from `production` to `staging` use following variable:
@@ -48,12 +63,15 @@ Add to `config/services.php` file:
    'client_secret' => env('ANIKEEN_ID_SECRET'),
    'redirect' => env('ANIKEEN_ID_CALLBACK_URL'),
    'base_url' => env('ANIKEEN_ID_BASE_URL'),
+    'webhook_secret' => env('ANIKEEN_ID_WEBHOOK_SECRET'),
 ],
 ```

+## Sign in with Anikeen ID
+
 ### Event Listener

-In Laravel 11, the default EventServiceProvider provider was removed. Instead, add the listener using the listen method on the Event facade, in your `AppServiceProvider` boot method:
+Since Laravel 11, the default EventServiceProvider provider was removed. Instead, add the listener using the listen method on the Event facade, in your `AppServiceProvider` boot method:

 ```php
 public function boot(): void
@@ -64,21 +82,19 @@ public function boot(): void
 }
 ```

-### Registering Middleware
+### User model

-Append it to the global middleware stack in your application's `bootstrap/app.php` file:
+Your users table needs the user's Anikeen ID and their tokens:

 ```php
->withMiddleware(function (Middleware $middleware) {
-    $middleware->web(append: [
-        \Anikeen\Id\Http\Middleware\CreateFreshApiToken::class,
-    ]);
-})
+Schema::table('users', function (Blueprint $table) {
+    $table->string('anikeen_id')->nullable()->unique();
+    $table->text('anikeen_id_access_token')->nullable();
+    $table->text('anikeen_id_refresh_token')->nullable();
+});
 ```

-### Implementing Billable
-
-To implement the `Billable` trait, you need to add the `Billable` trait to your user model.
+Add the `Billable` trait to the user model. Keep the tokens encrypted and out of JSON:

 ```php
 use Anikeen\Id\Billable;
@@ -87,11 +103,489 @@ class User extends Authenticatable
 {
    use Billable;

-    // Your model code...
+    protected $hidden = ['password', 'remember_token', 'anikeen_id_access_token', 'anikeen_id_refresh_token'];
+
+    protected function casts(): array
+    {
+        return [
+            'anikeen_id_access_token' => 'encrypted',
+            'anikeen_id_refresh_token' => 'encrypted',
+        ];
+    }
 }
 ```

-then, you can use the `Billable` trait methods in your user model.
+All user methods (`$user->orders()`, `$user->subscriptions()`, …) call the API with the user's
+access token from `anikeen_id_access_token`.
+
+### Login and callback
+
+Ask for the scopes your app needs (see [Scope](src/Id/Enums/Scope.php)). To sell orders and
+subscriptions, a shop typically asks for:
+
+```php
+use Laravel\Socialite\Facades\Socialite;
+
+Route::get('auth/redirect', fn () => Socialite::driver('anikeen')
+    ->scopes(['user:read', 'addresses:read', 'orders', 'subscriptions'])
+    ->redirect());
+
+Route::get('auth/callback', function () {
+    $account = Socialite::driver('anikeen')->user();
+
+    $user = User::updateOrCreate(['anikeen_id' => $account->getId()], [
+        'name' => $account->getName() ?: $account->getNickname(),
+        'email' => $account->getEmail(),
+        'anikeen_id_access_token' => $account->token,
+        'anikeen_id_refresh_token' => $account->refreshToken,
+    ]);
+
+    Auth::login($user, remember: true);
+
+    return redirect()->intended('/');
+});
+```
+
+Access tokens expire. Get a new one with the refresh token (or send the user through the login
+again):
+
+```php
+$result = app(\Anikeen\Id\AnikeenId::class)->refreshToken($user->anikeen_id_refresh_token);
+
+if ($result->success()) {
+    $user->update([
+        'anikeen_id_access_token' => $result->data()->access_token,
+        'anikeen_id_refresh_token' => $result->data()->refresh_token,
+    ]);
+}
+```
+
+### Change the default access token / refresh token field name
+
+If your access / refresh token fields differ from the default `anikeen_id_access_token` / `anikeen_id_refresh_token`, you can specify the field name in the `AppServiceProvider` boot method:
+
+```php
+use Anikeen\Id\AnikeenId;
+
+public function boot(): void
+{
+    AnikeenId::useAccessTokenField('anikeen_id_access_token');
+    AnikeenId::useRefreshTokenField('anikeen_id_refresh_token');
+}
+```
+
+## Payments
+
+### Which way fits?
+
+| You want to sell | Use | Token | Who starts the payment |
+|---|---|---|---|
+| One-off purchases (digital or physical goods) | [Orders](#selling-an-order) | user | the user, on Anikeen ID |
+| Something that recurs (a pass, a plan) | [Subscriptions](#subscriptions) | user | the user, on Anikeen ID |
+| Several subscriptions in one step | [Checkout sessions](#checkout-sessions-the-user-confirms-several-subscriptions-at-once) | user or app | the user, on Anikeen ID |
+| Usage billing from your backend, without the user online | [App subscriptions](#app-subscriptions-trusted-apps-no-user-token) | app | your app (trusted apps only) |
+
+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. Anikeen ID shows the items, asks
+for missing addresses, takes the payment and writes the invoice. Trusted apps (operated by
+Anikeen) can also charge directly; see [Trusted apps](#trusted-apps).
+
+The flow, as in a typical shop:
+
+1. The user signs in with Anikeen ID ([above](#sign-in-with-anikeen-id)).
+2. Your app creates the order: `$user->orders()->create([...])`.
+3. Redirect the user to `$order->confirmationUrl($returnUrl)`.
+4. The user confirms and pays on Anikeen ID, then comes back to `$returnUrl?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.
+
+### Selling an order
+
+```php
+use Anikeen\Id\Exceptions\ResourceException;
+
+$order = $user->orders()->create([
+    'billing_address_id' => $user->getUserData()->billing_address_id,
+    'items' => [
+        ['type' => 'digital', 'name' => 'Sticker pack', 'unit' => 'piece', 'units' => 1, 'gross_price' => '9.99'],
+    ],
+]);
+
+$shopOrder = ShopOrder::create(['user_id' => $user->id, 'anikeen_id' => $order->id, 'status' => $order->status]); // your own order model
+
+return redirect()->away($order->confirmationUrl(route('orders.return', $shopOrder)));
+// later: https://shop.test/orders/1/return?status=completed&order=01J…
+```
+
+When the user has no billing address on Anikeen ID yet, pass one instead of the ID. A name and
+the country are enough; the user completes it on the confirmation page:
+
+```php
+'billing_address' => ['first_name' => 'Ada', 'last_name' => 'Lovelace', 'country_iso' => 'DE', 'email' => $user->email],
+```
+
+Back in your app, read the order to know its state:
+
+```php
+Route::get('orders/{shopOrder}/return', function (ShopOrder $shopOrder) {
+    $order = auth()->user()->orders()->find($shopOrder->anikeen_id);
+
+    $shopOrder->update(['status' => $order->status]);
+
+    return redirect()->route('orders.show', $shopOrder);
+});
+```
+
+The order's `status`:
+
+| `status` | Meaning |
+|---|---|
+| `draft` | Created, not confirmed by the user yet |
+| `pending` | Confirmed, the payment is still processing |
+| `completed` | Paid |
+| `cancelled` | The user cancelled, or it wasn't confirmed within 24 hours |
+
+`return_url` must have the origin 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.
+
+`checkout()` on such a draft throws `ConfirmationRequiredException`; its `confirmationUrl`
+points to the same page. Trusted apps keep checking out directly.
+
+### Prices and 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 % |
+
+Give each item either `gross_price` (VAT included, what the user pays) or `price` (net), per unit.
+`unit` is `piece` or `onetime` for orders; `units` is the quantity. Subscription prices are always
+net per unit (`hour`, `day`, `week`, `month`, `year`).
+
+To show a total before the user confirms, ask for a preview:
+
+```php
+$preview = app(\Anikeen\Id\AnikeenId::class)->createOrderPreview([
+    'country_iso' => 'DE',
+    'items' => [['type' => 'physical', 'name' => 'T-shirt', 'gross_price' => '24.90', 'unit' => 'piece', 'units' => 1]],
+])->shift();
+
+$preview->gross_total;
+```
+
+### Physical goods and shipments
+
+Physical goods need a shipping address (`first_name`, `last_name`, `address`, `postal_code`,
+`city`, `country_iso`). The user can change both addresses on the confirmation page, so read the
+shipping address from the order (or the `order.completed` webhook) before you ship. An item's
+`image_url` is copied to Anikeen ID and stays visible on the order and invoice:
+
+```php
+$order = $user->orders()->create([
+    'billing_address_id' => $addressId,
+    'shipping_address' => ['first_name' => 'Ada', 'last_name' => 'Lovelace', 'address' => 'Main St', 'house_number' => '1', 'postal_code' => '10115', 'city' => 'Berlin', 'country_iso' => 'DE'],
+    'items' => [
+        ['type' => 'physical', 'name' => 'T-shirt', 'unit' => 'piece', 'units' => 1, 'gross_price' => '24.90', 'image_url' => 'https://shop.test/img/shirt.png'],
+        ['type' => 'physical-reduced', 'name' => 'Artbook', 'unit' => 'piece', 'units' => 1, 'gross_price' => '19.95'],
+    ],
+]);
+```
+
+Once a paid order is sent, create a shipment. Anikeen ID adds its delivery note to the user's
+order documents (with the tracking link), mails it to the user (`'notify_customer' => false` if
+your shop sends its own mail) and sends `order.shipped` to your webhook endpoints.
+Without `items`, everything physical that is left is shipped; partial deliveries name the items:
+
+```php
+$order = $user->orders()->find($orderId);
+
+$shipment = $order->shipments()->create([
+    'carrier' => 'DHL',
+    'tracking_number' => '00340434161234567890',
+    'tracking_url' => 'https://www.dhl.de/…?piececode=00340434161234567890',
+    // 'items' => [['order_item_id' => $itemId, 'units' => 1]],
+]);
+
+$shipment->number;          // LS-2026-0001
+$shipment->deliveryNote();  // the delivery note as PDF
+```
+
+To know what is left to ship, compare the order's items with its shipments:
+
+```php
+$items = $order->orderItems()->toArray();     // id, type, name, units, …
+$shipments = $order->shipments()->toArray();  // each with items: [{order_item_id, units}]
+```
+
+Only the app that created the order (or a trusted app) can ship it, and only once it is paid.
+
+### Subscriptions
+
+Subscriptions work like orders: create a draft, let the user confirm it, read it back.
+
+```php
+$subscription = $user->subscriptions()->create([
+    'name' => 'Pixel Stream Pass',
+    'description' => 'All streams, every month',
+    'unit' => 'month',
+    'price' => 6.714286,           // net per unit, 7.99 with 19 % VAT
+]);
+
+return redirect()->away($subscription->confirmationUrl(route('pass.return')));
+// later: https://shop.test/pass/return?status=completed&subscription=01J…
+```
+
+After the return, read the subscription and check its state:
+
+```php
+$subscription = $user->subscriptions()->find($id);
+
+if ($subscription->isActive()) {
+    // grant access
+}
+```
+
+`status()` returns one of the `Anikeen\Id\Enums\SubscriptionStatus` constants (the API sends the
+same value as `status`):
+
+| `status()` | Meaning | `isActive()` |
+|---|---|---|
+| `draft` | Created, not confirmed by the user yet | no |
+| `trial` | Running, in its trial period | yes |
+| `active` | Running and billed | yes |
+| `paused` | Runs until the paid period ends, then expires (`resume()` to continue) | yes |
+| `cancelling` | Runs until a scheduled cancellation takes effect | yes |
+| `expired` | Paused and ran out; `resume()` starts a new period | no |
+| `cancelled` | Cancelled for good | no |
+
+There are shortcuts for each: `isDraft()`, `isTrial()`, `isPaused()`, `isCancelling()`,
+`isExpired()`, `isCancelled()`. App subscriptions (`appSubscriptions()`) have the same methods.
+
+#### Free trials
+
+Give a subscription a free trial with `trial_days` (1–365, counted from the user's confirmation or
+the checkout) or a fixed `trial_ends_at` (ISO 8601, in the future), not both. The subscription
+starts right away with `status` `trial` and nothing billed; the first period is billed when the
+trial ends. `trial_once` refuses the trial if the user already had one with your app in the same
+`group` (422 when creating, 409 `trial_already_used` when checking out):
+
+```php
+$subscription = $user->subscriptions()->create([
+    'name' => 'Pixel Stream Pass',
+    'unit' => 'month',
+    'price' => 6.714286,
+    'trial_days' => 14,
+    'trial_once' => true,
+]);
+```
+
+A few days before the trial ends, Anikeen ID sends `subscription.trial_will_end`
+(`EventType::SUBSCRIPTION_TRIAL_WILL_END`), e.g. to remind the user; `data.payment_method_missing`
+tells you whether the user still has to add a payment method. Cancelling during the trial
+bills nothing. Trials work the same for app subscriptions and per subscription of a checkout
+session.
+
+By default the user needs a payment method to confirm a trial. With `trial_payment_method`
+`TrialPaymentMethod::OPTIONAL` (only together with a trial; `TrialPaymentMethod::REQUIRED` is the
+default) the user can confirm it without one, as long as nothing else has to be paid: in a
+checkout session every subscription has to be such a trial. The confirmation page tells the user
+to add a payment method before the trial ends. If there is still none then, the subscription is
+**cancelled** at the trial's end instead of billed: `status` `cancelled`, `cancellation_reason`
+`CancellationReason::TRIAL_ENDED_WITHOUT_PAYMENT_METHOD`, `subscription.cancelled` with
+`data.reason` set to the same value, and no `subscription.renewed`. Adding a payment method later
+doesn't bring it back – create a new subscription. The trial still counts for `trial_once`.
+Anikeen ID also mails the user a few days before such a trial ends without a payment method.
+
+```php
+use Anikeen\Id\Enums\CancellationReason;
+use Anikeen\Id\Enums\TrialPaymentMethod;
+use Anikeen\Id\Webhooks\EventType;
+
+$subscription = $user->appSubscriptions()->create([
+    'group' => $teamId,
+    'name' => 'Uptimr Pro',
+    'unit' => 'month',
+    'price' => 19.00,
+    'trial_days' => 14,
+    'trial_payment_method' => TrialPaymentMethod::OPTIONAL,
+]);
+
+// in your webhook handler
+$data = $event['data'];
+
+match ($event['type']) {
+    EventType::SUBSCRIPTION_TRIAL_WILL_END => $data['payment_method_missing']
+        ? Reminder::addPaymentMethod($data['object']['id'])
+        : null,
+    EventType::SUBSCRIPTION_CANCELLED => $data['reason'] === CancellationReason::TRIAL_ENDED_WITHOUT_PAYMENT_METHOD
+        ? Pass::downgrade($data['object']['id'])
+        : Pass::revoke($data['object']['id']),
+    default => null,
+};
+```
+
+#### Discounts
+
+A `discount` (e.g. a coupon) lowers the price of billed periods: every discounted period gets a
+negative line with the `label` next to its usage on the same bill, until the discount ends.
+
+```php
+$subscription = $user->subscriptions()->create([
+    'name' => 'Pixel Stream Pass',
+    'unit' => 'month',
+    'price' => 6.714286,
+    'discount' => [
+        'label' => 'SUMMER20',         // shown to the user, e.g. the coupon code
+        'percent_off' => 20,           // or 'amount_off' => 1.50 (net, per period)
+        'duration' => 'repeating',     // once, repeating or forever
+        'duration_in_periods' => 3,    // only for repeating
+    ],
+]);
+
+$subscription->discount;               // {label, percent_off, amount_off, duration, duration_in_periods, periods_remaining}
+```
+
+A period is one unit of the subscription (a month for monthly prices). A free trial isn't a
+billed period: the discount starts with the first paid one. `periods_remaining` counts down with
+every billed period (null for `forever`, 0 once it ended); then `subscription.discount_ended`
+(`EventType::SUBSCRIPTION_DISCOUNT_ENDED`) is sent. A discount can't be combined with a
+`monthly_cap`. It is set when the subscription is created (app subscriptions and checkout
+sessions alike) and changed afterwards with
+[`change()`](#changing-running-subscriptions-trusted-apps). A resize (`predecessor_id`) doesn't
+carry it over: send the successor the rest (`'duration' => 'repeating'`,
+`'duration_in_periods' => $old->discount->periods_remaining`).
+
+### Webhooks
+
+Anikeen ID sends `order.*`, `subscription.*` and `checkout.*` events to the webhook endpoints of
+your app (see [`EventType`](src/Id/Webhooks/EventType.php) for all of them). Verify each request
+with the raw body and answer 2xx within 10 seconds; failed deliveries are retried for about three
+days.
+
+Exclude the route from CSRF protection in `bootstrap/app.php`:
+
+```php
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->validateCsrfTokens(except: ['webhooks/*']);
+})
+```
+
+```php
+use Anikeen\Id\Exceptions\SignatureVerificationException;
+use Anikeen\Id\Webhooks\EventType;
+use Anikeen\Id\Webhooks\Webhook;
+
+Route::post('webhooks/anikeen', function (Request $request) {
+    try {
+        $event = Webhook::constructEvent($request->getContent(), $request->header('Anikeen-Signature'), config('services.anikeen.webhook_secret'));
+    } catch (SignatureVerificationException) {
+        abort(400);
+    }
+
+    if (! ProcessedEvent::firstOrCreate(['id' => $event['id']])->wasRecentlyCreated) {
+        return response()->noContent(); // already handled
+    }
+
+    $object = $event['data']['object'];
+
+    match ($event['type']) {
+        EventType::ORDER_COMPLETED => Shop::fulfil($object['id'], $object['shipping_address']),
+        EventType::ORDER_CANCELLED => Shop::release($object['id']),
+        EventType::SUBSCRIPTION_ACTIVATED => Pass::grant($object['id']),
+        EventType::SUBSCRIPTION_CANCELLED => Pass::revoke($object['id']),
+        EventType::CHECKOUT_COMPLETED => Panel::provision($object['subscription_ids']),
+        default => null,
+    };
+
+    return response()->noContent();
+});
+```
+
+`data.object` is the order, subscription or checkout session as the API returns it. Events can
+arrive more than once or out of order: use `$event['id']` to skip duplicates, and reload the
+object through the API when the current state matters. The admin panel can send a
+`webhook.test` event to check your endpoint.
+
+`subscription.renewed` (`EventType::SUBSCRIPTION_RENEWED`) is sent once for every period booked
+on the user's monthly order, **the first one included**, with `$event['data']['period']`:
+`{subscription_id, period_start, period_end, periods, first_period, unit, order_id, order_item_id,
+items, currency_iso, net_amount}` (`net_amount` after a discount). `first_period` is `true` for the
+subscription's first paid period (the checkout, sent after `subscription.activated`, or the first
+period after a free trial) and `false` for every later one (renewals, resuming an expired
+subscription, a unit change applied right away). Hourly subscriptions renew every hour, so this
+event is **opt-in**: select it explicitly for your endpoint, `*` doesn't include it.
+
+```php
+if ($event['type'] === EventType::SUBSCRIPTION_RENEWED) {
+    $period = $event['data']['period'];
+    // e.g. a commission per paid period; the first one may count differently
+    Commission::record($period['subscription_id'], $period['net_amount'], first: $period['first_period']);
+}
+```
+`order.*` events list the order's `items` and `invoice` like
+[app orders](#app-orders-trusted-apps-no-user-token).
+
+### Errors
+
+Every failed request throws `Anikeen\Id\Exceptions\ApiException`, with the user's token as
+well as with the app's (`app*()`). It carries:
+
+- `status`: the HTTP status (also `getCode()`), `0` when Anikeen ID could not be reached,
+- `error`: a stable error code when Anikeen ID sent one (e.g. `billing_address_missing`,
+  `already_cancelled`), otherwise `null`,
+- `getMessage()`: Anikeen ID's reason,
+- `isNotFound()` (404), `isConflict()` (409) and `isTemporary()` (no response, 429 or 5xx: retry
+  later).
+
+```php
+use Anikeen\Id\Exceptions\ApiException;
+
+try {
+    $order = $user->orders()->create($attributes);
+} catch (ApiException $e) {
+    if ($e->isTemporary()) {
+        return back()->with('error', 'Anikeen ID is not reachable right now, please try again.');
+    }
+
+    report($e);
+
+    return back()->with('error', $e->getMessage());
+}
+```
+
+Failed lists (`$user->invoices()`, …) throw `CollectionException`, a subclass of `ApiException`.
+`ConfirmationRequiredException` (a third-party app called `checkout()`, see above) stays its own
+type. All of them extend `ResourceException`, so existing `catch (ResourceException $e)` blocks
+keep working.
+
+### Testing
+
+Develop against staging (`ANIKEEN_ID_MODE=staging`) with an OAuth client registered there.
+Payments on staging run in Stripe's test mode: pay with Stripe's
+[test cards](https://docs.stripe.com/testing), e.g. `4242 4242 4242 4242` with any future expiry
+date and any CVC. No money is charged.
+Point `ANIKEEN_ID_BASE_URL` at your own Anikeen ID instance if you run one locally.
+
+In unit tests, swap the HTTP client for a Guzzle `MockHandler`:
+
+```php
+$mock = new \GuzzleHttp\Handler\MockHandler([
+    new \GuzzleHttp\Psr7\Response(201, ['Content-Type' => 'application/json'], json_encode(['data' => ['id' => '01JORDER', 'status' => 'draft']])),
+]);
+
+$this->app->instance(AnikeenId::class, (new AnikeenId())->setHttpClient(new \GuzzleHttp\Client([
+    'handler' => \GuzzleHttp\HandlerStack::create($mock),
+    'base_uri' => 'https://id.test/api/',
+])));
+```
+
+## Trusted apps
+
+Apps operated by Anikeen can be marked as trusted. They can charge without asking the user and
+use their own token (client credentials), so billing keeps working when the user's login expired.

 ### App subscriptions (trusted apps, no user token)

@@ -127,7 +621,8 @@ subscriptions it created (plus those of clients delegated to it).
 Failures throw `Anikeen\Id\Exceptions\ApiException` with `status` (0 = not reachable), a stable
 `error` code (`already_active`, `already_cancelled`, `not_active`, `already_paused`,
 `already_resumed`, `billing_address_missing`, `not_changeable`, `subscription_not_found`,
-`idempotency_key_conflict`) and `isNotFound()`, `isConflict()`, `isTemporary()`:
+`idempotency_key_conflict`, `in_checkout_session`, `trial_already_used`, `proration_not_possible`,
+`credit_exceeds_bill`) and `isNotFound()`, `isConflict()`, `isTemporary()`:

 ```php
 try {
@@ -143,6 +638,70 @@ try {
 }
 ```

+### Confirmable orders (trusted apps)
+
+Trusted apps can charge one-off orders right away (`'checkout' => true`). With `'confirm' => true`
+the user confirms and pays the order on Anikeen ID instead, like for a third-party app – e.g. a
+top-up the user starts in your app: Anikeen ID shows the order with VAT, the billing address and
+the payment method (one can be added there) and takes the payment.
+
+```php
+$order = app(AnikeenId::class)->createOrderForUser($team->owner->anikeen_id, [
+    'group' => $team->id,
+    'confirm' => true,
+    'return_url' => route('billing.topup.done'),   // same origin as one of your redirect URIs
+    'metadata' => ['topup' => $topup->id],          // returned as is, also in the order webhooks
+    'items' => [['type' => 'digital', 'name' => 'Credit', 'unit' => 'onetime', 'units' => 1, 'gross_price' => '10.00']],
+])->data;
+
+return redirect()->away($order->confirmation_url);
+// later: https://console.test/billing/topup/done?status=completed&order=01K…
+```
+
+`confirm` needs `items` and can't be combined with `checkout` or a `transaction` (422). The draft
+expires after 24 hours (`expires_at`): it is cancelled, `confirmation_url` becomes null and
+`checkout()` answers 409 `confirmation_expired`. Follow the order through its webhooks:
+`order.created`, then `order.completed` once paid (`order.payment_failed` for a declined charge)
+or `order.cancelled` when the user declines or it expires. `return_url` and `metadata` work for
+every order, also with the user's token (`$user->orders()->create([...])`).
+
+### Changing running subscriptions (trusted apps)
+
+`update()` changes a subscription before its checkout (afterwards only the description).
+`change()` changes price, unit, name, description or discount of a running subscription, like a
+plan change (send only what changes):
+
+```php
+use Anikeen\Id\Resources\AppSubscription;
+
+// upgrade now, prorated: the unused rest of the period is credited, the new price charged for it
+$subscription->change(['apply' => AppSubscription::APPLY_NOW, 'price' => '0.0274', 'name' => 'Cloud Server M']);
+
+// downgrade from the next period on
+$subscription->change(['apply' => AppSubscription::APPLY_PERIOD_END, 'price' => '4.99']);
+$subscription->scheduled_change;       // {applies_at, name, description, unit, price, discount, created_at}
+$subscription->cancelScheduledChange(); // keep the current values after all
+```
+
+- `now` credits the unused part of the current period at the rate it was billed at and charges
+  the rest at the new price, both on the user's open bill. A new `unit` starts a new, fully billed
+  period now. A downgrade whose credit would exceed the open bill is refused with 409
+  `credit_exceeds_bill`: schedule it for the period end instead. 409 `proration_not_possible` when
+  the current period wasn't billed to the subscription (e.g. a takeover); `period_end` works.
+- `period_end` changes nothing now; the next period is billed at the new values. A new
+  `period_end` change replaces the scheduled one, `now` drops it.
+- During a free trial nothing was billed: both just change what the trial ends in.
+- `discount` replaces the discount from the next billed period on, `null` ends it. When the unit
+  changes, a discount that counts in periods or an `amount_off` has to be sent again (422).
+- Subscriptions with a monthly cap change only with `period_end`.
+- Only running subscriptions can change: 409 `not_changeable` for drafts (use `update()`), paused,
+  cancelling, expired and cancelled ones.
+
+When a change takes effect (right away or at the period end), Anikeen ID sends
+`subscription.updated` (`EventType::SUBSCRIPTION_UPDATED`) with the old values of the changed
+fields in `$event['data']['previous_attributes']`. Telling the user about a price increase (and
+getting consent where needed) is up to your app.
+
 ### App orders (trusted apps, no user token)

 Orders that bill the app's subscriptions, read with the app's token (scope `orders:client`):
@@ -157,6 +716,67 @@ Each order has `status` (`processing` = current month, still collecting; `pendin
 paid; `completed`; `cancelled`), the totals, `payment_attempts`, `next_payment_attempt_at` (null =
 no more automatic retries) and `last_payment_error`.

+Collective (monthly) orders are kept **per app**: your subscriptions are never billed on the same
+order as another app's, even if both use the same `group` (or none); clients delegated to your app
+bill on your app's orders. `$order->oauth_client_id` is the app that bills the order.
+
+Orders also list their lines and their invoice, e.g. to show a team's invoices or to attribute
+amounts (commissions) per subscription:
+
+```php
+$order = app(AnikeenId::class)->appOrders()->find($orderId);
+
+foreach ($order->items as $item) {
+    $item->subscription_id;                     // null for lines that bill no subscription
+    $item->period_start; $item->period_end;     // ISO 8601, the end is exclusive; null without a period
+    $item->net_amount;                          // units × price, rounded to cents
+    $item->discount;                            // {label, percent_off, amount_off} on a discount line, else null
+}
+
+$order->invoice;                                // null until paid, then {id, number, status, …, pdf_url}
+$pdf = app(AnikeenId::class)->appOrders()->invoicePdf($orderId); // the invoice PDF (binary)
+```
+
+The net amount actually billed for a subscription is the sum of `net_amount` of its lines
+(discount lines are negative). `invoicePdf()` throws `ApiException` with 404 `invoice_not_found`
+before the order is paid and 409 `invoice_not_ready` while the PDF is still being rendered
+(usually seconds after the payment; try again later). Legacy orders from before collective orders
+were kept per app (`oauth_client_id` null) can also bill other apps' subscriptions: there `items`
+lists only your lines (the totals are the whole order's), `invoice->pdf_url` is null and
+`invoicePdf()` throws `ApiException` with 403 `invoice_includes_other_apps`.
+
+### Billing portal links (trusted apps)
+
+A "Manage billing" button for a user whose token your app doesn't have (e.g. the owner of a team
+your app bills): create a link to the user's billing pages on Anikeen ID with the app's token
+(scope `subscriptions:client` or `orders:client`). Like Stripe's customer portal, it works
+**without a login**:
+
+```php
+Route::post('teams/{team}/billing', function (Team $team) {
+    return redirect()->away($team->owner->appBillingPortalUrl([
+        'return_url' => route('teams.show', $team), // "Back to <app>"; same origin as one of your redirect URIs
+        'group' => $team->id,                       // only this group's subscriptions, orders and invoices
+        'flow' => 'invoices',                       // overview (default), payment_method, payment_method_update,
+                                                    // invoices, subscriptions or orders
+    ]));
+});
+
+app(AnikeenId::class)->createBillingPortalLinkForUser($userId, ['flow' => 'payment_method_update']);
+// {object: "billing_portal_link", url, user_id, flow, group, return_url, expires_at}
+```
+
+The link is **single use** and valid for about 15 minutes: create it when the user clicks and
+redirect right away; don't store, mail or reuse it (a second request with the same link, e.g. a
+reload, gets a 403). Opening it starts a portal session for that user that needs no login and
+signs nobody in: only the billing pages of the `flow`, only what bills your app's subscriptions
+(of the `group`), with "Back to *app*". The user's account settings, other apps and OAuth consent
+stay behind the normal login; signed in as another account, the portal still shows only the
+link's user. The session ends after an hour without activity or on "Back to *app*".
+`payment_method_update` leads straight to replacing the payment method (e.g. after a failed
+payment) and back to `return_url`. For the signed-in user with their own token,
+`$user->billingPortalUrl()` stays available.
+
 ### Checkout sessions (the user confirms several subscriptions at once)

 Instead of checking subscriptions out itself, an app can let the user confirm them on Anikeen ID,
@@ -166,7 +786,7 @@ period, confirms (all subscriptions start, or none) or cancels, and returns to `
 Open sessions expire after 24 hours with their drafts. Trusted apps can still check out directly;
 sessions are opt-in.

-Example: the Console's builder ("Jetzt kaufen") with several products and coupon prices:
+Example: a cart with several products and coupon prices:

 ```php
 use Anikeen\Id\Exceptions\ApiException;
@@ -214,76 +834,22 @@ While a session is open, its subscriptions can't be checked out or repriced by t
 `subscription.activated` / `subscription.cancelled` are still sent per subscription, before the
 `checkout.*` event of the session.

-### Selling as a third-party app (user confirms on Anikeen ID)

-Apps that are not trusted can create orders and subscriptions for the signed-in user (user token),
-but can't charge them. The user confirms on Anikeen ID and comes back to your `return_url`:
+## API authentication
+
+Use this when your own API accepts access tokens issued by Anikeen ID.
+
+### Registering Middleware
+
+To call your API from your own frontend with the user's session, append the middleware to the
+web middleware group in your application's `bootstrap/app.php` file:

 ```php
-use Anikeen\Id\Exceptions\ConfirmationRequiredException;
-
-$order = $user->orders()->create([
-    'billing_address_id' => $addressId,
-    'items' => [['type' => 'digital', 'name' => 'Sticker pack', 'unit' => 'piece', 'units' => 1, 'gross_price' => '9.99']],
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->web(append: [
+        \Anikeen\Id\Http\Middleware\CreateFreshApiToken::class,
    ]);
-
-return redirect($order->confirmationUrl(route('shop.done')));
-// later: https://your-app.test/shop/done?status=completed&order=01J…
-```
-
-`return_url` must have the origin of one of your app's redirect URIs. `status` is `completed`,
-`pending` (payment still processing) or `cancelled`; check it with `$user->orders()->find($id)`
-instead of trusting the query string. Subscriptions work the same way
-(`$user->subscriptions()->create([...])->confirmationUrl(...)`, `&subscription=…`).
-Unconfirmed bookings are cancelled after 24 hours.
-
-`checkout()` on such a draft throws `ConfirmationRequiredException`; its `confirmationUrl`
-points to the same page. Trusted apps keep checking out directly.
-
-### Webhooks
-
-Anikeen ID sends `order.*`, `subscription.*` and `checkout.*` events to the webhook endpoints of your app (set up
-in the Anikeen ID admin panel, which also shows the signing secret `whsec_…`). Verify each request
-with the raw body and answer 2xx within 10 seconds; failed deliveries are retried for about three days.
-
-```php
-use Anikeen\Id\Exceptions\SignatureVerificationException;
-use Anikeen\Id\Webhooks\EventType;
-use Anikeen\Id\Webhooks\Webhook;
-
-Route::post('webhooks/anikeen', function (Request $request) {
-    try {
-        $event = Webhook::constructEvent($request->getContent(), $request->header('Anikeen-Signature'), config('services.anikeen.webhook_secret'));
-    } catch (SignatureVerificationException) {
-        abort(400);
-    }
-
-    match ($event['type']) {
-        EventType::ORDER_COMPLETED => Shop::fulfil($event['data']['object']['id']),
-        EventType::SUBSCRIPTION_CANCELLED => Panel::suspend($event['data']['object']['id']),
-        EventType::CHECKOUT_COMPLETED => Panel::provision($event['data']['object']['subscription_ids']),
-        default => null,
-    };
-
-    return response()->noContent();
-})->withoutMiddleware(VerifyCsrfToken::class);
-```
-
-Events can arrive more than once or out of order: use `$event['id']` to skip duplicates, and
-reload the object through the API when the current state matters.
-
-### Change the default access token / refresh token field name
-
-If you access / refresh token fields differs from the default `anikeen_id_access_token` / `anikeen_id_refresh_token`, you can specify the field name in the `AppServiceProvider` boot method:
-
-```php
-use Anikeen\Id\AnikeenId;
-
-public function boot(): void
-{
-    AnikeenId::useAccessTokenField('anikeen_id_access_token');
-    AnikeenId::useRefreshTokenField('anikeen_id_refresh_token');
-}
+})
 ```

 ### Implementing Auth (API tokens)
@@ -371,70 +937,36 @@ $anikeenId = $anikeenId->withClientSecret('abc123');
 $anikeenId = $anikeenId->withToken('abcdef123456');
 ```

-#### Error handling for an unsuccessful query:
+#### Results and resources
+
+Low-level methods on `AnikeenId` (e.g. `getAuthedUser()`, `createOrderPreview()`,
+`refreshToken()`) return a `Result`. Check it before you use it:

 ```php
-$result = $anikeenId->sshKeysByUserId('someInvalidId');
+$result = $anikeenId->getAuthedUser();

-// Check, if the query was successfully
 if (!$result->success()) {
    die('Ooops: ' . $result->error());
 }
+
+$user = $result->shift(); // the object, or the first item of a list
 ```

-#### Shift result to get single key data:
-
-```php
-$result = $anikeenId->sshKeysByUserId('someValidId');
-
-$sshKey = $result->shift();
-
-echo $sshKey->name;
-```
+Resource methods (`$user->orders()`, `$anikeenId->sshKeysByUserId()`, …) return objects and throw
+`ApiException` instead (see [Errors](#errors)).

 ## Examples

-#### Get User SSH Key
+#### Get User SSH Keys
+
+Uses the app's own token (client credentials):

 ```php
-$anikeenId = new Anikeen\IdAnikeenId();
-
-$anikeenId->setClientId('abc123');
-
-// Get SSH Key by User ID
-$result = $anikeenId->sshKeysByUserId('someValidId');
-
-// Check, if the query was successfully
-if (!$result->success()) {
-    die('Ooops: ' . $result->error());
-}
-
-// Shift result to get single key data
-$sshKey = $result->shift();
+$sshKeys = app(Anikeen\Id\AnikeenId::class)->sshKeysByUserId($anikeenUserId);

+foreach ($sshKeys->toArray() as $sshKey) {
    echo $sshKey->name;
-```
-
-#### Create Order Preview
-
-```php
-$anikeenId = new \Anikeen\Id\AnikeenId();
-
-// Create new Order Preview
-$result = $anikeenId->createOrderPreview([
-    'country_iso' => 'de',
-    'items' => [
-        [
-            'type' => 'physical',
-            'name' => 'Test',
-            'price' => 2.99,
-            'unit' => 'onetime',
-            'units' => 1,
-        ]
-    ]
-])->shift();
-
-echo $preview->gross_total;
+}
 ```

 #### OAuth Tokens
@@ -442,22 +974,13 @@ echo $preview->gross_total;
 ```php
 $anikeenId = new Anikeen\Id\AnikeenId();

-$anikeenId->setClientId('abc123');
 $anikeenId->setToken('abcdef123456');

-$result = $anikeenId->getAuthedUser();
-
-$user = $userResult->shift();
+$user = $anikeenId->getAuthedUser()->shift();
 ```

 ```php
-$anikeenId->setToken('uvwxyz456789');
-
-$result = $anikeenId->getAuthedUser();
-```
-
-```php
-$result = $anikeenId->withToken('uvwxyz456789')->getAuthedUser();
+$user = $anikeenId->withToken('uvwxyz456789')->getAuthedUser()->shift();
 ```

 #### Facade
@@ -465,14 +988,14 @@ $result = $anikeenId->withToken('uvwxyz456789')->getAuthedUser();
 ```php
 use Anikeen\Id\Facades\AnikeenId;

-AnikeenId::withClientId('abc123')->withToken('abcdef123456')->getAuthedUser();
+AnikeenId::withToken('abcdef123456')->getAuthedUser();
 ```

 ## Documentation

 <!-- GENERATED-DOCS -->

-[**OAuth Scopes Enums**](https://github.com/anikeen-com/id/blob/main/src/Enums/Scope.php)
+[**OAuth Scopes Enums**](https://github.com/anikeen-com/id/blob/main/src/Id/Enums/Scope.php)

 ## Development

@@ -482,10 +1005,6 @@ AnikeenId::withClientId('abc123')->withToken('abcdef123456')->getAuthedUser();
 composer test
 ```

-```shell
-BASE_URL=xxxx CLIENT_ID=xxxx CLIENT_KEY=yyyy CLIENT_ACCESS_TOKEN=zzzz composer test
-```
-
 #### Generate Documentation

 ```shell
@@ -15,15 +15,15 @@
  "require": {
    "php": "^8.2",
    "ext-json": "*",
-    "illuminate/support": "^11.0|^12.0|^13.0",
-    "illuminate/console": "^11.0|^12.0|^13.0",
+    "illuminate/support": "^12.69|^13.0",
+    "illuminate/console": "^12.69|^13.0",
    "guzzlehttp/guzzle": "^7.8",
    "socialiteproviders/manager": "^4.6",
-    "firebase/php-jwt": "^6.10|^7.0"
+    "firebase/php-jwt": "^7.0"
  },
  "require-dev": {
-    "laravel/framework": "^11.0|^12.0|^13.0",
-    "orchestra/testbench": "^9.0|^10.0|^11.0",
+    "laravel/framework": "^12.69|^13.0",
+    "orchestra/testbench": "^10.0|^11.0",
    "phpunit/phpunit": "^11.0|^12.0"
  },
  "autoload": {
@@ -0,0 +1,90 @@
+<?php
+
+namespace Anikeen\Id\Concerns;
+
+use Anikeen\Id\Enums\SubscriptionStatus;
+
+/**
+ * The state of a subscription, derived from its fields the same way Anikeen ID derives `status`
+ * (so it also works with responses that only carry the fields).
+ */
+trait HasSubscriptionStatus
+{
+    /**
+     * One of the SubscriptionStatus constants: draft, trial, active, paused, cancelling, expired
+     * or cancelled.
+     */
+    public function status(): string
+    {
+        $active = (bool) $this->active;
+        $started = !empty($this->starts_at);
+
+        return match (true) {
+            (bool) $this->cancelled => SubscriptionStatus::CANCELLED,
+            !$active && !$started => SubscriptionStatus::DRAFT,
+            $active && !empty($this->cancels_at) => SubscriptionStatus::CANCELLING,
+            $active && !$this->autorenew => SubscriptionStatus::PAUSED,
+            $active && !empty($this->trial_ends_at) && strtotime($this->trial_ends_at) > time() => SubscriptionStatus::TRIAL,
+            $active => SubscriptionStatus::ACTIVE,
+            !$this->autorenew && $started => SubscriptionStatus::EXPIRED,
+            default => SubscriptionStatus::INACTIVE,
+        };
+    }
+
+    /**
+     * Not checked out or confirmed yet (third-party apps: send the user to confirmationUrl()).
+     */
+    public function isDraft(): bool
+    {
+        return $this->status() === SubscriptionStatus::DRAFT;
+    }
+
+    /**
+     * Running and paid: active, in trial, paused or with a scheduled cancellation. Grant access
+     * while this is true.
+     */
+    public function isActive(): bool
+    {
+        return in_array($this->status(), [SubscriptionStatus::TRIAL, SubscriptionStatus::ACTIVE, SubscriptionStatus::PAUSED, SubscriptionStatus::CANCELLING], true);
+    }
+
+    /**
+     * In its free trial: running, nothing billed until trial_ends_at.
+     */
+    public function isTrial(): bool
+    {
+        return $this->status() === SubscriptionStatus::TRIAL;
+    }
+
+    /**
+     * Paused: runs until the paid period ends, then expires (resume() to continue).
+     */
+    public function isPaused(): bool
+    {
+        return $this->status() === SubscriptionStatus::PAUSED;
+    }
+
+    /**
+     * Running until a scheduled cancellation takes effect.
+     */
+    public function isCancelling(): bool
+    {
+        return $this->status() === SubscriptionStatus::CANCELLING;
+    }
+
+    /**
+     * Paused and ran out: resume() starts a new period.
+     */
+    public function isExpired(): bool
+    {
+        return $this->status() === SubscriptionStatus::EXPIRED;
+    }
+
+    /**
+     * Cancelled for good.
+     */
+    public function isCancelled(): bool
+    {
+        return $this->status() === SubscriptionStatus::CANCELLED;
+    }
+}
@@ -2,6 +2,8 @@

 namespace Anikeen\Id\Concerns;

+use Anikeen\Id\AnikeenId;
+use Anikeen\Id\Exceptions\ApiException;
 use Anikeen\Id\Resources\AppCheckoutSessions;
 use Anikeen\Id\Resources\AppOrders;
 use Anikeen\Id\Resources\AppSubscriptions;
@@ -65,4 +67,20 @@ trait ManagesSubscriptions
    {
        return new AppOrders($this);
    }
+
+    /**
+     * A link to the user's billing pages on Anikeen ID that needs no login, created with the app's
+     * own token (trusted apps only, scope subscriptions:client or orders:client), e.g. for a
+     * "Manage billing" button; see AnikeenId::createBillingPortalLinkForUser() for the attributes
+     * (return_url, group, flow). Single use and valid for about 15 minutes: create it when the
+     * user clicks and redirect right away.
+     *
+     * @param array{return_url?: null|string, group?: null|string, flow?: null|string} $attributes
+     *
+     * @throws ApiException
+     */
+    public function appBillingPortalUrl(array $attributes = []): string
+    {
+        return app(AnikeenId::class)->createBillingPortalLinkForUser($this->appSubscriptions()->userId(), $attributes)->url;
+    }
 }
@@ -2,9 +2,11 @@

 namespace Anikeen\Id\Concerns;

+use Anikeen\Id\Exceptions\ApiException;
 use Anikeen\Id\Resources\AppCheckoutSessions;
 use Anikeen\Id\Resources\AppOrders;
 use Anikeen\Id\Result;
+use Anikeen\Id\Support\AppRequest;
 use Throwable;

 /**
@@ -29,11 +31,48 @@ trait ManagesUserBilling
        return new AppCheckoutSessions();
    }

+    /**
+     * A link to a user's billing pages on Anikeen ID that needs no login, like Stripe's customer
+     * portal, e.g. for a "Manage billing" button of an app that bills another user's account (a
+     * team owner) without that user's token (trusted apps, scope subscriptions:client or
+     * orders:client). The link is single use and valid for about 15 minutes: create it when the
+     * user clicks and redirect right away, don't store it. It opens a portal session for that user
+     * only (no login, nobody signed in) with only the flow's billing pages and only what bills the
+     * app's subscriptions (of the group), leading back to return_url; it ends after an hour
+     * without activity.
+     *
+     * @param string $userId The user's Anikeen ID.
+     * @param array{
+     *     return_url?: null|string,
+     *     group?: null|string,
+     *     flow?: null|string
+     * } $attributes return_url: "Back to the app" (same origin as one of the app's redirect URIs,
+     *               422 otherwise).
+     *               group: only this group's subscriptions and the orders, invoices and
+     *               transactions billing them.
+     *               flow: overview (default), payment_method, payment_method_update (straight to
+     *               replacing the payment method, e.g. after a failed payment), invoices,
+     *               subscriptions or orders.
+     * @return object {object: "billing_portal_link", url, user_id, flow, group, return_url, expires_at}
+     *
+     * @throws ApiException 403 untrusted app or missing scope, 404 unknown user, 422 validation
+     */
+    public function createBillingPortalLinkForUser(string $userId, array $attributes = []): object
+    {
+        return AppRequest::send('POST', sprintf('v1/client/users/%s/billing-portal', $userId), $attributes)->data;
+    }
+
    /**
     * Create an order for a user (VAT from the billing address). With `checkout`, it is paid right
     * away: with the given `transaction` (a payment captured elsewhere) or by charging the user's
     * default payment method (402 when declined; the order stays pending and is retried).
     *
+     * With `confirm`, the user confirms and pays it on Anikeen ID instead (e.g. a top-up): the
+     * order stays a draft with `confirmation_url` (send the user there) and is cancelled if not
+     * confirmed within 24 hours (`expires_at`; afterwards checking it out answers 409
+     * "confirmation_expired"). Webhooks: order.created, order.completed once paid, or
+     * order.cancelled when the user declines or it expires.
+     *
     * @param string $userId The user's Anikeen ID.
     * @param array{
     *     group?: string,
@@ -43,11 +82,18 @@ trait ManagesUserBilling
     *     shipping_address?: array,
     *     items: array<array{type: string, name: string, description?: string, image_url?: string, price?: float|string, gross_price?: float|string, unit: string, units: int}>,
     *     checkout?: bool,
+     *     confirm?: bool,
+     *     return_url?: null|string,
+     *     metadata?: null|array,
     *     transaction_id?: string,
     *     transaction?: array,
     *     invoice_date?: string,
     *     currency_iso?: string
-     * } $attributes
+     * } $attributes confirm: needs items, can't be combined with checkout or a transaction.
+     *               return_url: where the user returns after confirming, with `status` and
+     *               `order` (same origin as one of the app's redirect URIs, 422 otherwise).
+     *               metadata: the app's own data (max. 50 keys), returned as is in the API and
+     *               the order webhooks.
     * @throws Throwable
     */
    public function createOrderForUser(string $userId, array $attributes): Result
@@ -0,0 +1,13 @@
+<?php
+
+namespace Anikeen\Id\Enums;
+
+/**
+ * `cancellation_reason` of a subscription (and `data.reason` of `subscription.cancelled`): why
+ * Anikeen ID's billing ended it. Null when the user, the app or an admin cancelled it.
+ */
+class CancellationReason
+{
+    /** Its free trial (`trial_payment_method` optional) ended without a payment method: cancelled at the trial's end, nothing billed. */
+    const TRIAL_ENDED_WITHOUT_PAYMENT_METHOD = 'trial_ended_without_payment_method';
+}
@@ -0,0 +1,33 @@
+<?php
+
+namespace Anikeen\Id\Enums;
+
+/**
+ * The state of a subscription, see Subscription::status() and AppSubscription::status().
+ */
+class SubscriptionStatus
+{
+    /** Created, not checked out or confirmed by the user yet. */
+    const DRAFT = 'draft';
+
+    /** Running and billed, in its trial period. */
+    const TRIAL = 'trial';
+
+    /** Running and billed. */
+    const ACTIVE = 'active';
+
+    /** Paused: runs until its paid period ends, then expires. */
+    const PAUSED = 'paused';
+
+    /** Running until a scheduled cancellation takes effect. */
+    const CANCELLING = 'cancelling';
+
+    /** Paused and ran out: can be resumed (new period) or cancelled. */
+    const EXPIRED = 'expired';
+
+    /** Cancelled for good. */
+    const CANCELLED = 'cancelled';
+
+    /** None of the above. */
+    const INACTIVE = 'inactive';
+}
@@ -0,0 +1,20 @@
+<?php
+
+namespace Anikeen\Id\Enums;
+
+/**
+ * `trial_payment_method` of a subscription with a free trial: whether the user needs a payment
+ * method to confirm it. Null on subscriptions without a trial.
+ */
+class TrialPaymentMethod
+{
+    /** A payment method is needed to confirm the trial (the default). */
+    const REQUIRED = 'required';
+
+    /**
+     * The trial can be confirmed without a payment method (if nothing else has to be paid). If the
+     * user still has none when the trial ends, the subscription is cancelled then instead of billed
+     * (`cancellation_reason` CancellationReason::TRIAL_ENDED_WITHOUT_PAYMENT_METHOD).
+     */
+    const OPTIONAL = 'optional';
+}
@@ -2,6 +2,7 @@

 namespace Anikeen\Id\Exceptions;

+use Anikeen\Id\Result;
 use Throwable;

 /**
@@ -19,6 +20,30 @@ class ApiException extends ResourceException
        parent::__construct($message, $status, $previous);
    }

+    /**
+     * The exception for a failed request: Anikeen ID's message and error code, the HTTP status
+     * (0 when there was no response).
+     */
+    public static function fromResult(Result $result): static
+    {
+        $body = is_object($result->data) ? $result->data : null;
+
+        return new static(
+            rtrim((string) ($body->message ?? $result->error()), '.'),
+            $result->response()?->getStatusCode() ?? 0,
+            $body->error ?? null,
+            $result->exception,
+        );
+    }
+
+    /**
+     * The exception for a request that got no response (network error, timeout).
+     */
+    public static function unreachable(Throwable $previous): static
+    {
+        return new static(sprintf('Anikeen ID is not reachable: %s', $previous->getMessage()), 0, null, $previous);
+    }
+
    public function isNotFound(): bool
    {
        return $this->status === 404;
@@ -2,10 +2,10 @@

 namespace Anikeen\Id\Exceptions;

-use Anikeen\Id\Result;
-use Exception;
-
-class CollectionException extends Exception
+/**
+ * A list request failed. Like ApiException it carries the HTTP status (also as getCode()) and
+ * Anikeen ID's error code.
+ */
+class CollectionException extends ApiException
 {
-
 }
@@ -36,7 +36,12 @@ class AppCheckoutSessions
     *         predecessor_id?: null|string,
     *         vat_rate?: float,
     *         payload?: null|array,
-     *         ends_at?: null|string
+     *         ends_at?: null|string,
+     *         trial_days?: null|int,
+     *         trial_ends_at?: null|string,
+     *         trial_once?: bool,
+     *         trial_payment_method?: null|string,
+     *         discount?: null|array{label: string, percent_off?: float|string, amount_off?: float|string, duration: string, duration_in_periods?: int}
     *     }>,
     *     return_url?: null|string,
     *     metadata?: null|array,
@@ -45,6 +50,11 @@ class AppCheckoutSessions
     * } $attributes return_url must share scheme, host and port with one of the app's redirect
     *               URIs; the user comes back to it with `status` and `checkout_session`. A
     *               repeated idempotency_key returns the first session instead of a new one.
+     *               trial_days / trial_ends_at give a subscription a free trial from the user's
+     *               confirmation on; trial_once is allowed on one subscription per group.
+     *               trial_payment_method `optional`: the session can be confirmed without a
+     *               payment method only if all of its subscriptions are such trials.
+     *               discount: see AppSubscriptions::create(); the confirmation page shows it.
     *
     * @throws ApiException 422 validation (e.g. return_url), 409 "idempotency_key_conflict"
     */
@@ -13,9 +13,22 @@ use Illuminate\Database\Eloquent\Model;
 * scope orders:client) - of one user ($user->appOrders()) or of all users
 * (app(AnikeenId::class)->appOrders()). Nothing is requested until a method is called.
 *
- * Each order is an object with id, user_id, group, status (processing|pending|completed|cancelled),
- * is_collective, net_total, vat_total, gross_total, currency_iso, created_at, paid_at,
- * payment_attempts, next_payment_attempt_at and last_payment_error ({code, message} or null).
+ * Each order is an object with id, user_id, oauth_client_id (the app that bills it: collective
+ * orders are kept per app, even for the same group; null on legacy orders that billed several
+ * apps), group, metadata, status (processing|pending|completed|cancelled), is_collective,
+ * net_total, vat_total, gross_total, currency_iso, created_at, paid_at, payment_attempts,
+ * next_payment_attempt_at, last_payment_error ({code, message} or null), and
+ *
+ * - items: the order's lines of the app's subscriptions (all lines, except on legacy orders that
+ *   also billed other apps), each {id, name, description, type, image_url, units, unit,
+ *   price, vat_rate, subscription_id, meter, monthly_cap, discount, period_start, period_end,
+ *   net_amount, vat_amount, gross_amount}. period_end is exclusive (the start of the next
+ *   period); both are null for lines without a period. discount ({label, percent_off,
+ *   amount_off}) marks the negative line of a subscription's discount, else null. The net amount
+ *   a subscription was billed is the sum of net_amount of its lines.
+ * - invoice: null until the order is paid, then {id, number, type, status (pending while the PDF
+ *   is being rendered, then completed), service_period_from, service_period_to, created_at,
+ *   pdf_url}; see invoicePdf().
 */
 class AppOrders
 {
@@ -81,6 +94,22 @@ class AppOrders
        return !$this->billable || $order->user_id === $this->userId() ? $order : null;
    }

+    /**
+     * The PDF of an order's invoice (binary string, with the embedded e-invoice), the same as its
+     * `invoice.pdf_url` with the app's token.
+     *
+     * @throws ApiException 404 "order_not_found", 404 "invoice_not_found" (not paid yet),
+     *                      409 "invoice_not_ready" (still being rendered, try again later)
+     */
+    public function invoicePdf(string $orderId): string
+    {
+        if ($this->billable && !$this->find($orderId)) {
+            throw new ApiException('Order not found.', 404, 'order_not_found');
+        }
+
+        return (string) AppRequest::send('GET', sprintf('v1/client/orders/%s/invoice', $orderId))->response()?->getBody();
+    }
+
    private function userId(): string
    {
        return (new AppSubscriptions($this->billable))->userId();
@@ -2,6 +2,7 @@

 namespace Anikeen\Id\Resources;

+use Anikeen\Id\Concerns\HasSubscriptionStatus;
 use Anikeen\Id\Exceptions\ApiException;
 use Anikeen\Id\Support\AppRequest;
 use DateTimeInterface;
@@ -24,7 +25,12 @@ use JsonSerializable;
 * @property bool $active
 * @property bool $autorenew
 * @property bool $cancelled
- * @property ?string $status "active" or "inactive"
+ * @property ?string $status draft, trial, active, paused, cancelling, expired or cancelled, see status()
+ * @property ?string $cancels_at when a scheduled cancellation takes effect
+ * @property ?string $trial_ends_at
+ * @property ?string $trial_payment_method required or optional with a trial (TrialPaymentMethod), null without
+ * @property ?string $cancellation_reason why the billing cancelled it (CancellationReason), null otherwise
+ * @property ?object $discount {label, percent_off, amount_off, duration, duration_in_periods, periods_remaining}; periods_remaining is null for `forever`, 0 once it ended
 * @property ?string $starts_at
 * @property ?string $ends_at
 * @property ?string $accounting_at
@@ -33,9 +39,18 @@ use JsonSerializable;
 * @property ?array $payload
 * @property ?string $idempotency_key
 * @property ?string $checkout_session_id the checkout session the user confirms it in, if any
+ * @property ?object $scheduled_change {applies_at, name, description, unit, price, discount, created_at}: a change() for the period end
 */
 class AppSubscription implements JsonSerializable
 {
+    use HasSubscriptionStatus;
+
+    /** change(): prorated, right away. */
+    public const APPLY_NOW = 'now';
+
+    /** change(): from the next period on (scheduled_change until then). */
+    public const APPLY_PERIOD_END = 'period_end';
+
    public function __construct(protected object $data)
    {
    }
@@ -54,6 +69,7 @@ class AppSubscription implements JsonSerializable
     * Change a subscription (send only what changes). Before checkout everything can change;
     * afterwards only the description, which names what the customer pays for and is shown
     * on their bills, e.g. `$subscription->update(['description' => 'web-01.example.com'])`.
+     * Prices of running subscriptions change with change().
     *
     * @throws ApiException
     */
@@ -62,6 +78,51 @@ class AppSubscription implements JsonSerializable
        return $this->send('PUT', '', $attributes);
    }

+    /**
+     * Change a running subscription (send only what changes), like a plan change:
+     *
+     * - `apply: now`: prorated – the unused rest of the current period is credited at the rate it
+     *   was billed at and charged at the new price on the user's open bill. A new unit starts a
+     *   new, fully billed period now. A downgrade whose credit exceeds the open bill is refused
+     *   (409 "credit_exceeds_bill"): schedule it for the period end instead.
+     * - `apply: period_end`: nothing changes now; the subscription has `scheduled_change` and the
+     *   next period is billed at the new values. A new scheduled change replaces the previous one.
+     *
+     * During a free trial nothing was billed, so both just change what the trial ends in.
+     * Webhook `subscription.updated` (with `data.previous_attributes`) when the change takes effect.
+     *
+     * @param array{
+     *     apply: string,
+     *     price?: float|string,
+     *     unit?: string,
+     *     name?: string,
+     *     description?: null|string,
+     *     discount?: null|array{label: string, percent_off?: float|string, amount_off?: float|string, duration: string, duration_in_periods?: int}
+     * } $attributes apply: self::APPLY_NOW or self::APPLY_PERIOD_END.
+     *               unit: a recurring unit (hour, day, week, month, year).
+     *               discount: replaces the discount from the next billed period on, null ends it;
+     *               required with a new unit when the current one counts in periods or is an
+     *               amount_off. Subscriptions with a monthly cap change only at the period end.
+     *
+     * @throws ApiException 409 "not_changeable" (not running: draft, paused, cancelling, …),
+     *                      "proration_not_possible", "credit_exceeds_bill",
+     *                      "billing_address_missing"; 422 validation
+     */
+    public function change(array $attributes): self
+    {
+        return $this->send('PUT', '/change', $attributes);
+    }
+
+    /**
+     * Drop the change scheduled for the period end (nothing happens without one).
+     *
+     * @throws ApiException
+     */
+    public function cancelScheduledChange(): self
+    {
+        return $this->send('DELETE', '/change');
+    }
+
    /**
     * Activate the subscription and bill its first period.
     *
@@ -49,6 +49,11 @@ class AppSubscriptions
     *     vat_rate?: float,
     *     payload?: null|array,
     *     ends_at?: null|string,
+     *     trial_days?: null|int,
+     *     trial_ends_at?: null|string,
+     *     trial_once?: bool,
+     *     trial_payment_method?: null|string,
+     *     discount?: null|array{label: string, percent_off?: float|string, amount_off?: float|string, duration: string, duration_in_periods?: int},
     *     idempotency_key?: null|string
     * } $attributes With an idempotency_key (max. 191 characters), a retried call returns the
     *               subscription created by the first one instead of a duplicate.
@@ -56,8 +61,21 @@ class AppSubscriptions
     *               at most 2 decimals, not below price; null = no cap).
     *               predecessor_id: the subscription this one replaces (a resize; same user and
     *               app, checked out, not cancelled): both share the monthly cap within a month.
+     *               trial_days: a free trial of 1–365 days from the checkout on (status `trial`,
+     *               nothing billed; the first period is billed when it ends), or
+     *               trial_ends_at: a fixed end of the trial (ISO 8601, in the future), not both.
+     *               trial_once: refuse the trial if the user already had one with the app in the
+     *               same group (422 here, 409 "trial_already_used" on checkout).
+     *               trial_payment_method: TrialPaymentMethod::REQUIRED (default) or ::OPTIONAL,
+     *               only with a trial: with `optional` the user may confirm it without a payment
+     *               method, and without one at the trial's end it is cancelled instead of billed.
+     *               discount: e.g. a coupon, as a negative line next to each billed period:
+     *               label (shown to the user, max. 100 characters), percent_off (0.01–100) or
+     *               amount_off (net per period, at most the price), duration `once` (the first
+     *               billed period), `repeating` (duration_in_periods billed periods) or
+     *               `forever`. Not combinable with a monthly_cap.
     *
-     * @throws ApiException
+     * @throws ApiException 422 validation, 409 "idempotency_key_conflict", …
     */
    public function create(array $attributes): AppSubscription
    {
@@ -7,6 +7,7 @@ use Anikeen\Id\Exceptions\CollectionException;
 use Anikeen\Id\Helpers\Paginator;
 use Anikeen\Id\Result;
 use Closure;
+use GuzzleHttp\Exception\GuzzleException;
 use GuzzleHttp\Psr7\Response;
 use JsonSerializable;
 use Throwable;
@@ -34,10 +35,15 @@ abstract class BaseCollection implements JsonSerializable
     */
    protected function __construct(callable $callable)
    {
+        try {
            $this->result = $callable();
+        } catch (GuzzleException $e) {
+            // no response at all (connection refused, timeout)
+            throw CollectionException::unreachable($e);
+        }

        if (!$this->result->success()) {
-            throw new CollectionException(sprintf('%s for collection [%s]', rtrim($this->result->data->message, '.'), get_called_class()), $this->result->response->getStatusCode());
+            throw CollectionException::fromResult($this->result);
        }
    }

@@ -2,9 +2,10 @@

 namespace Anikeen\Id\Resources;

+use Anikeen\Id\Exceptions\ApiException;
 use Anikeen\Id\Exceptions\ConfirmationRequiredException;
-use Anikeen\Id\Exceptions\ResourceException;
 use Anikeen\Id\Result;
+use GuzzleHttp\Exception\GuzzleException;
 use JsonSerializable;

 #[\AllowDynamicProperties]
@@ -13,11 +14,17 @@ abstract class BaseResource implements JsonSerializable
    public Result $result;

    /**
-     * @throws ResourceException
+     * @throws ApiException the request failed (status, error code; a ResourceException)
+     * @throws ConfirmationRequiredException the user has to confirm it on Anikeen ID
     */
    public function __construct(callable $callable)
    {
+        try {
            $this->result = $callable();
+        } catch (GuzzleException $e) {
+            // no response at all (connection refused, timeout)
+            throw ApiException::unreachable($e);
+        }

        if (!$this->result->success()) {
            if (($this->result->data->error ?? null) === 'confirmation_required') {
@@ -28,7 +35,7 @@ abstract class BaseResource implements JsonSerializable
                );
            }

-            throw new ResourceException(sprintf('%s for resource [%s]', rtrim($this->result->data->message, '.'), get_called_class()), $this->result->response->getStatusCode());
+            throw ApiException::fromResult($this->result);
        }

        foreach ($this->result->data as $key => $value) {
@@ -8,7 +8,14 @@ use Throwable;

 /**
 * @property string $id
- * @property null|string $confirmation_url where the user confirms it (third-party apps)
+ * @property null|string $confirmation_url where the user confirms it (third-party apps, or `confirm`)
+ * @property null|string $oauth_client_id the app that bills the order: the app that created it, or for a monthly
+ *                                        (collective) order the app whose subscriptions it bills; collective orders
+ *                                        are kept per app. null for Anikeen's own (and legacy orders of several apps)
+ * @property null|string $group
+ * @property null|object $metadata the app's own data, returned as is
+ * @property null|string $return_url where the user returns after confirming
+ * @property null|string $expires_at when a draft created with `confirm` is cancelled unless confirmed
 */
 class Order extends BaseResource
 {
@@ -53,10 +60,14 @@ class Order extends BaseResource
     *           country_iso: string,
     *           phone_number: null|string,
     *           email: null|string
-     *      }
+     *      },
+     *      group?: null|string,
+     *      metadata?: null|array
     *  } $attributes The order data:
     *    - billing_address:  Billing address (ISO 3166-1 alpha-2 country code)
     *    - shipping_address: Shipping address for physical items (first name, last name, address, postal code, city, ISO 3166-1 alpha-2 country code)
+     *    - group:            The app's group (optional)
+     *    - metadata:         The app's own data (max. 50 keys), only while the order is a draft (optional)
     * @throws Throwable
     */
    public function update(array $attributes = []): self
@@ -69,6 +80,8 @@ class Order extends BaseResource
    /**
     * Checkout given order from the current user.
     *
+     * A draft created with `confirm` can't be checked out once it expired (409 "confirmation_expired").
+     *
     * @throws Throwable
     */
    public function checkout(): self
@@ -48,6 +48,10 @@ class Orders extends BaseCollection
     *          phone_number: null|string,
     *          email: null|string
     *     },
+     *     group?: null|string,
+     *     confirm?: bool,
+     *     return_url?: null|string,
+     *     metadata?: null|array,
     *     items: array<array{
     *         type:         string,
     *         name:         string,
@@ -61,6 +65,10 @@ class Orders extends BaseCollection
     * } $attributes The order data:
     *   - billing_address:  Billing address (ISO 3166-1 alpha-2 country code)
     *   - shipping_address: Shipping address for physical items (first name, last name, address, postal code, city, ISO 3166-1 alpha-2 country code)
+     *   - group:            The app's group, e.g. a team (optional)
+     *   - confirm:          Trusted apps: leave confirming and paying to the user (confirmation_url, expires after 24 hours; optional)
+     *   - return_url:       Where the user returns after confirming (same origin as one of the app's redirect URIs; optional)
+     *   - metadata:         The app's own data (max. 50 keys), returned as is in the API and webhooks (optional)
     *   - items:            Array of order items:
     *       - type:        digital, physical or physical-reduced (VAT category)
     *       - price/gross_price: net or gross unit price, one of both
@@ -4,6 +4,7 @@ namespace Anikeen\Id\Resources;

 use Anikeen\Id\Concerns\HasBillable;
 use Anikeen\Id\Concerns\HasConfirmationUrl;
+use Anikeen\Id\Concerns\HasSubscriptionStatus;
 use Anikeen\Id\Contracts\AppTokenRepository;
 use Throwable;

@@ -18,13 +19,24 @@ use Throwable;
 * @property ?string $predecessor_id the subscription this one replaced (a resize); they share the monthly cap
 * @property float $vat_rate
 * @property array $payload
+ * @property bool $active
+ * @property bool $autorenew
+ * @property bool $cancelled
+ * @property ?string $status draft, trial, active, paused, cancelling, expired or cancelled, see status()
+ * @property ?string $starts_at
 * @property string $ends_at
+ * @property ?string $cancels_at when a scheduled cancellation takes effect
+ * @property ?string $trial_ends_at
+ * @property ?string $trial_payment_method required or optional with a trial (TrialPaymentMethod), null without
+ * @property ?string $cancellation_reason why the billing cancelled it (CancellationReason), null otherwise
+ * @property ?object $discount {label, percent_off, amount_off, duration, duration_in_periods, periods_remaining}; periods_remaining is null for `forever`, 0 once it ended
 * @property null|string $confirmation_url where the user confirms it (third-party apps)
 */
 class Subscription extends BaseResource
 {
    use HasBillable;
    use HasConfirmationUrl;
+    use HasSubscriptionStatus;

    /**
     * Update a given subscription from the current user.
@@ -24,7 +24,12 @@ class Subscriptions extends BaseCollection
     *      predecessor_id?: null|string,
     *      vat_rate: float,
     *      payload: null|array,
-     *      ends_at: null|string
+     *      ends_at: null|string,
+     *      trial_days?: null|int,
+     *      trial_ends_at?: null|string,
+     *      trial_once?: bool,
+     *      trial_payment_method?: null|string,
+     *      discount?: null|array{label: string, percent_off?: float|string, amount_off?: float|string, duration: string, duration_in_periods?: int}
     *  } $attributes The subscription data:
     *    - group:          The group (optional)
     *    - name:           The name
@@ -36,6 +41,11 @@ class Subscriptions extends BaseCollection
     *    - vat_rate:       The VAT rate (required when set)
     *    - payload:        The payload (optional)
     *    - ends_at:        The end date (optional)
+     *    - trial_days:     A free trial of 1–365 days from the user's confirmation on (optional)
+     *    - trial_ends_at:  Or a fixed end of the free trial (ISO 8601, in the future; optional)
+     *    - trial_once:     Refuse the trial if the user already had one with the app in the group (optional)
+     *    - trial_payment_method: TrialPaymentMethod::REQUIRED (default) or ::OPTIONAL, only with a trial (optional)
+     *    - discount:       A discount per billed period, see AppSubscriptions::create() (optional)
     * @throws Throwable
     */
    public function create(array $attributes): Subscription
@@ -18,9 +18,34 @@ final class EventType
    public const SUBSCRIPTION_ACTIVATED = 'subscription.activated';
    public const SUBSCRIPTION_PAUSED = 'subscription.paused';
    public const SUBSCRIPTION_RESUMED = 'subscription.resumed';
+    /** `data.reason`: why the billing cancelled it (CancellationReason, e.g. a trial that ended without a payment method), else null. */
    public const SUBSCRIPTION_CANCELLED = 'subscription.cancelled';
    public const SUBSCRIPTION_EXPIRED = 'subscription.expired';

+    /**
+     * The free trial of a running subscription ends in a few days (see trial_ends_at); billing
+     * starts then. `data.payment_method_missing`: the user has no payment method yet (with
+     * trial_payment_method `optional` the subscription then ends with the trial).
+     */
+    public const SUBSCRIPTION_TRIAL_WILL_END = 'subscription.trial_will_end';
+
+    /** The last discounted period of a subscription was billed; the following ones are billed at the full price. */
+    public const SUBSCRIPTION_DISCOUNT_ENDED = 'subscription.discount_ended';
+
+    /**
+     * The price, unit, name, description or discount of a running subscription changed (right away
+     * or at the period end); `data.previous_attributes` has the changed fields' old values.
+     */
+    public const SUBSCRIPTION_UPDATED = 'subscription.updated';
+
+    /**
+     * A period of a subscription was booked on its collective order, the first one included;
+     * `data.period` describes it, `data.period.first_period` is true for the subscription's first
+     * paid period (checkout or the end of a free trial). Opt-in: only endpoints that select this
+     * event get it (not through `*`).
+     */
+    public const SUBSCRIPTION_RENEWED = 'subscription.renewed';
+
    /** The user confirmed a checkout session: all of its subscriptions are running (sent after their subscription.activated). */
    public const CHECKOUT_COMPLETED = 'checkout.completed';

@@ -4,6 +4,8 @@ namespace Anikeen\Id\Tests;

 use Anikeen\Id\AnikeenId;
 use Anikeen\Id\Billable;
+use Anikeen\Id\Exceptions\ApiException;
+use GuzzleHttp\Psr7\Response;
 use Illuminate\Database\Eloquent\Model;

 class AppOrdersTest extends TestCase
@@ -68,4 +70,65 @@ class AppOrdersTest extends TestCase
        $this->assertNull($orders->find('o1'));
        $this->assertSame('o1', $orders->find('o1')->id);
    }
+
+    public function test_orders_list_their_lines_and_invoice(): void
+    {
+        $this->respond(200, ['data' => [
+            'id' => 'o1',
+            'user_id' => '01JUSER',
+            'group' => 'team-1',
+            'metadata' => ['topup' => '7'],
+            'items' => [
+                ['id' => 'i1', 'subscription_id' => '01JSUB', 'units' => 1, 'price' => 10, 'period_start' => '2026-11-01T00:00:00+00:00', 'period_end' => '2026-12-01T00:00:00+00:00', 'net_amount' => 10, 'discount' => null],
+                ['id' => 'i2', 'subscription_id' => '01JSUB', 'units' => 1, 'price' => -2, 'period_start' => '2026-11-01T00:00:00+00:00', 'period_end' => '2026-12-01T00:00:00+00:00', 'net_amount' => -2, 'discount' => ['label' => 'SUMMER20', 'percent_off' => 20, 'amount_off' => null]],
+            ],
+            'invoice' => ['id' => 'inv1', 'number' => 'RE-2026-0001', 'status' => 'completed', 'pdf_url' => 'https://id.test/api/v1/client/orders/o1/invoice'],
+        ]]);
+
+        $order = $this->owner()->appOrders()->find('o1');
+
+        $this->assertSame('7', $order->metadata->topup);
+        $this->assertSame(8, array_sum(array_map(fn ($item) => $item->net_amount, array_filter($order->items, fn ($item) => $item->subscription_id === '01JSUB'))));
+        $this->assertSame('SUMMER20', $order->items[1]->discount->label);
+        $this->assertSame('RE-2026-0001', $order->invoice->number);
+    }
+
+    public function test_the_invoice_pdf_is_downloaded_with_the_app_token(): void
+    {
+        $this->http->append(new Response(200, ['Content-Type' => 'application/pdf'], '%PDF-1.7 invoice'));
+        $this->respond(200, ['data' => ['id' => 'o1', 'user_id' => '01JUSER']]);
+        $this->http->append(new Response(200, ['Content-Type' => 'application/pdf'], '%PDF-1.7 invoice'));
+
+        $this->assertSame('%PDF-1.7 invoice', app(AnikeenId::class)->appOrders()->invoicePdf('o1'));
+        $this->assertSame('%PDF-1.7 invoice', $this->owner()->appOrders()->invoicePdf('o1'));
+
+        $calls = array_map(fn ($entry) => $entry['request']->getMethod() . ' ' . $entry['request']->getUri()->getPath() . ' ' . $entry['request']->getHeaderLine('Authorization'), $this->sent);
+        $this->assertSame([
+            'GET /api/v1/client/orders/o1/invoice Bearer app-token',
+            'GET /api/v1/client/orders/o1 Bearer app-token',
+            'GET /api/v1/client/orders/o1/invoice Bearer app-token',
+        ], $calls);
+    }
+
+    public function test_an_invoice_that_is_not_ready_is_a_conflict(): void
+    {
+        $this->respond(409, ['message' => 'The invoice document is still being created.', 'error' => 'invoice_not_ready']);
+        $this->respond(200, ['data' => ['id' => 'o1', 'user_id' => 'someone-else']]);
+
+        try {
+            app(AnikeenId::class)->appOrders()->invoicePdf('o1');
+            $this->fail('Expected an ApiException.');
+        } catch (ApiException $e) {
+            $this->assertTrue($e->isConflict());
+            $this->assertSame('invoice_not_ready', $e->error);
+        }
+
+        try {
+            $this->owner()->appOrders()->invoicePdf('o1');
+            $this->fail('Expected an ApiException.');
+        } catch (ApiException $e) {
+            $this->assertTrue($e->isNotFound());
+            $this->assertSame('order_not_found', $e->error);
+        }
+    }
 }
@@ -4,7 +4,10 @@ namespace Anikeen\Id\Tests;

 use Anikeen\Id\AnikeenId;
 use Anikeen\Id\Billable;
+use Anikeen\Id\Enums\CancellationReason;
+use Anikeen\Id\Enums\TrialPaymentMethod;
 use Anikeen\Id\Exceptions\ApiException;
+use Anikeen\Id\Resources\AppSubscription;
 use GuzzleHttp\Exception\ConnectException;
 use GuzzleHttp\Psr7\Request;
 use Illuminate\Database\Eloquent\Model;
@@ -174,6 +177,99 @@ class AppSubscriptionsTest extends TestCase
        }
    }

+    public function test_a_subscription_starts_with_a_free_trial(): void
+    {
+        $this->respond(201, $this->subscription());
+        $this->respond(200, $this->subscription(['active' => true, 'autorenew' => true, 'status' => 'trial', 'starts_at' => '2026-11-04T10:00:00+00:00', 'trial_ends_at' => date(DATE_ATOM, time() + 14 * 86400)]));
+
+        $subscription = $this->owner()->appSubscriptions()->create(['group' => 'team-1', 'name' => 'Pro', 'unit' => 'month', 'price' => '9.99', 'trial_days' => 14, 'trial_once' => true]);
+        $subscription->checkout();
+
+        $this->assertSame(['group' => 'team-1', 'name' => 'Pro', 'unit' => 'month', 'price' => '9.99', 'trial_days' => 14, 'trial_once' => true, 'user_id' => '01JUSER'], $this->sentJson(0));
+        $this->assertTrue($subscription->isTrial());
+        $this->assertTrue($subscription->isActive());
+    }
+
+    public function test_a_trial_can_be_confirmed_without_a_payment_method_and_end_cancelled(): void
+    {
+        $this->respond(201, $this->subscription(['trial_days' => 14, 'trial_payment_method' => 'optional']));
+        $this->respond(200, $this->subscription(['active' => false, 'cancelled' => true, 'status' => 'cancelled', 'starts_at' => '2026-11-04T10:00:00+00:00', 'trial_ends_at' => '2026-11-18T10:00:00+00:00', 'cancels_at' => '2026-11-18T10:00:00+00:00', 'trial_payment_method' => 'optional', 'cancellation_reason' => 'trial_ended_without_payment_method']));
+
+        $subscription = $this->owner()->appSubscriptions()->create(['name' => 'Pro', 'unit' => 'month', 'price' => '9.99', 'trial_days' => 14, 'trial_payment_method' => TrialPaymentMethod::OPTIONAL]);
+
+        $this->assertSame('optional', $this->sentJson(0)['trial_payment_method']);
+        $this->assertSame(TrialPaymentMethod::OPTIONAL, $subscription->trial_payment_method);
+
+        $ended = $this->owner()->appSubscriptions()->find('01JSUB');
+        $this->assertTrue($ended->isCancelled());
+        $this->assertSame(CancellationReason::TRIAL_ENDED_WITHOUT_PAYMENT_METHOD, $ended->cancellation_reason);
+    }
+
+    public function test_a_used_trial_is_refused_on_checkout(): void
+    {
+        $this->respond(201, $this->subscription());
+        $this->respond(409, ['message' => 'The user already had a free trial.', 'error' => 'trial_already_used']);
+
+        $subscription = $this->owner()->appSubscriptions()->create(['name' => 'Pro', 'unit' => 'month', 'price' => '9.99', 'trial_ends_at' => '2026-12-01T00:00:00+01:00', 'trial_once' => true]);
+
+        try {
+            $subscription->checkout();
+            $this->fail('Expected an ApiException.');
+        } catch (ApiException $e) {
+            $this->assertTrue($e->isConflict());
+            $this->assertSame('trial_already_used', $e->error);
+        }
+    }
+
+    public function test_a_subscription_is_created_with_a_discount(): void
+    {
+        $discount = ['label' => 'SUMMER20', 'percent_off' => 20, 'duration' => 'repeating', 'duration_in_periods' => 3];
+        $this->respond(201, $this->subscription(['discount' => [...$discount, 'amount_off' => null, 'periods_remaining' => 3]]));
+
+        $subscription = $this->owner()->appSubscriptions()->create(['name' => 'Pro', 'unit' => 'month', 'price' => '9.99', 'discount' => $discount]);
+
+        $this->assertSame($discount, $this->sentJson(0)['discount']);
+        $this->assertSame('SUMMER20', $subscription->discount->label);
+        $this->assertSame(3, $subscription->discount->periods_remaining);
+    }
+
+    public function test_a_running_subscription_is_changed_now_or_at_the_period_end(): void
+    {
+        $change = ['applies_at' => '2026-12-01T00:00:00+00:00', 'name' => 'Pro', 'description' => null, 'unit' => 'month', 'price' => 14.99, 'discount' => null, 'created_at' => '2026-11-04T10:00:00+00:00'];
+        $this->respond(200, $this->subscription(['active' => true, 'price' => 14.99]));
+        $this->respond(200, $this->subscription(['active' => true, 'price' => 14.99, 'scheduled_change' => $change]));
+        $this->respond(200, $this->subscription(['active' => true, 'price' => 14.99, 'scheduled_change' => null]));
+
+        $subscription = new AppSubscription((object) $this->subscription(['active' => true])['data']);
+
+        $this->assertSame(14.99, $subscription->change(['apply' => AppSubscription::APPLY_NOW, 'price' => '14.99', 'discount' => null])->price);
+        $this->assertSame('2026-12-01T00:00:00+00:00', $subscription->change(['apply' => AppSubscription::APPLY_PERIOD_END, 'unit' => 'month', 'name' => 'Pro'])->scheduled_change->applies_at);
+        $this->assertNull($subscription->cancelScheduledChange()->scheduled_change);
+
+        $this->assertSame([
+            'PUT /api/v1/client/subscriptions/01JSUB/change Bearer app-token',
+            'PUT /api/v1/client/subscriptions/01JSUB/change Bearer app-token',
+            'DELETE /api/v1/client/subscriptions/01JSUB/change Bearer app-token',
+        ], array_map(fn ($entry) => $entry['request']->getMethod() . ' ' . $entry['request']->getUri()->getPath() . ' ' . $entry['request']->getHeaderLine('Authorization'), $this->sent));
+        $this->assertSame(['apply' => 'now', 'price' => '14.99', 'discount' => null], $this->sentJson(0));
+        $this->assertSame(['apply' => 'period_end', 'unit' => 'month', 'name' => 'Pro'], $this->sentJson(1));
+    }
+
+    public function test_a_refused_change_carries_its_error_code(): void
+    {
+        $this->respond(409, ['message' => 'The credit would exceed the open bill.', 'error' => 'credit_exceeds_bill']);
+
+        $subscription = new AppSubscription((object) $this->subscription(['active' => true])['data']);
+
+        try {
+            $subscription->change(['apply' => AppSubscription::APPLY_NOW, 'price' => '1.99']);
+            $this->fail('Expected an ApiException.');
+        } catch (ApiException $e) {
+            $this->assertTrue($e->isConflict());
+            $this->assertSame('credit_exceeds_bill', $e->error);
+        }
+    }
+
    public function test_a_missing_user_id_is_reported(): void
    {
        $this->expectException(InvalidArgumentException::class);
@@ -2,7 +2,9 @@

 namespace Anikeen\Id\Tests;

+use Anikeen\Id\AnikeenId;
 use Anikeen\Id\Billable;
+use Anikeen\Id\Exceptions\ApiException;
 use Anikeen\Id\Exceptions\ConfirmationRequiredException;
 use Illuminate\Database\Eloquent\Model;

@@ -60,4 +62,44 @@ class CheckoutConfirmationTest extends TestCase
            $this->assertSame('https://id.anikeen.com/checkout/subscriptions/01JSUB', $e->confirmationUrl);
        }
    }
+
+    public function test_a_trusted_app_lets_the_user_confirm_its_order(): void
+    {
+        $this->respond(201, ['data' => ['id' => '01JORD', 'status' => 'draft', 'group' => 'team-1', 'metadata' => ['topup' => '7'], 'expires_at' => '2026-11-05T10:00:00+00:00', 'confirmation_url' => 'https://id.anikeen.com/checkout/orders/01JORD']]);
+
+        $result = app(AnikeenId::class)->createOrderForUser('01JUSER', [
+            'group' => 'team-1',
+            'confirm' => true,
+            'return_url' => 'https://console.test/billing/topup',
+            'metadata' => ['topup' => '7'],
+            'items' => [['type' => 'digital', 'name' => 'Credit', 'unit' => 'onetime', 'units' => 1, 'gross_price' => '10.00']],
+        ]);
+
+        $this->assertSame('POST /api/v1/admin/orders Bearer app-token', $this->sent[0]['request']->getMethod() . ' ' . $this->sent[0]['request']->getUri()->getPath() . ' ' . $this->sent[0]['request']->getHeaderLine('Authorization'));
+        $this->assertTrue($this->sentJson(0)['confirm']);
+        $this->assertSame('https://console.test/billing/topup', $this->sentJson(0)['return_url']);
+        $this->assertSame(['topup' => '7'], $this->sentJson(0)['metadata']);
+        $this->assertSame('01JUSER', $this->sentJson(0)['user_id']);
+        $this->assertSame('https://id.anikeen.com/checkout/orders/01JORD', $result->data->confirmation_url);
+        $this->assertSame('7', $result->data->metadata->topup);
+    }
+
+    public function test_an_expired_confirmation_is_a_conflict(): void
+    {
+        $this->respond(200, ['data' => []]);
+        $this->respond(201, ['data' => ['id' => '01JORD', 'status' => 'draft', 'confirmation_url' => 'https://id.anikeen.com/checkout/orders/01JORD']]);
+        $this->respond(409, ['message' => 'The order was not confirmed in time.', 'error' => 'confirmation_expired']);
+
+        $order = $this->owner()->orders()->create(['confirm' => true, 'return_url' => 'https://shop.test/done', 'metadata' => ['cart' => 1], 'items' => []]);
+
+        $this->assertSame(['confirm' => true, 'return_url' => 'https://shop.test/done', 'metadata' => ['cart' => 1], 'items' => []], $this->sentJson(1));
+
+        try {
+            $order->checkout();
+            $this->fail('Expected an ApiException.');
+        } catch (ApiException $e) {
+            $this->assertTrue($e->isConflict());
+            $this->assertSame('confirmation_expired', $e->error);
+        }
+    }
 }
@@ -139,6 +139,32 @@ class CheckoutSessionsTest extends TestCase
        $this->assertNull($user->checkoutSessions()->find('unknown'));
    }

+    public function test_session_subscriptions_carry_a_free_trial(): void
+    {
+        $this->respond(201, $this->sessionData());
+
+        $this->owner()->appCheckoutSessions()->create(['subscriptions' => [
+            ['group' => 'team-1', 'name' => 'Pro', 'unit' => 'month', 'price' => '9.99', 'trial_days' => 14, 'trial_once' => true],
+            ['group' => 'team-1', 'name' => 'Backup', 'unit' => 'month', 'price' => '1.99', 'trial_ends_at' => '2026-12-01T00:00:00+00:00'],
+        ]]);
+
+        $this->assertSame(14, $this->sentJson(0)['subscriptions'][0]['trial_days']);
+        $this->assertTrue($this->sentJson(0)['subscriptions'][0]['trial_once']);
+        $this->assertSame('2026-12-01T00:00:00+00:00', $this->sentJson(0)['subscriptions'][1]['trial_ends_at']);
+    }
+
+    public function test_session_subscriptions_carry_a_discount(): void
+    {
+        $this->respond(201, $this->sessionData());
+
+        $this->owner()->checkoutSessions()->create(['subscriptions' => [
+            ['name' => 'Pro', 'unit' => 'month', 'price' => 4.99, 'discount' => ['label' => 'WELCOME', 'amount_off' => '1.00', 'duration' => 'once']],
+        ]]);
+
+        $this->assertSame('POST /api/v1/checkout-sessions Bearer user-token', $this->request(0));
+        $this->assertSame(['label' => 'WELCOME', 'amount_off' => '1.00', 'duration' => 'once'], $this->sentJson(0)['subscriptions'][0]['discount']);
+    }
+
    public function test_nothing_is_requested_until_a_method_is_called(): void
    {
        $this->owner()->checkoutSessions();
@@ -159,5 +185,8 @@ class CheckoutSessionsTest extends TestCase
        $this->assertSame(['01JS1', '01JS2'], $event['data']['object']['subscription_ids']);
        $this->assertContains('checkout.expired', EventType::all());
        $this->assertContains('subscription.activated', EventType::all());
+        $this->assertContains('subscription.trial_will_end', EventType::all());
+        $this->assertContains('subscription.discount_ended', EventType::all());
+        $this->assertContains('subscription.updated', EventType::all());
    }
 }
@@ -4,6 +4,7 @@ namespace Anikeen\Id\Tests;

 use Anikeen\Id\AnikeenId;
 use Anikeen\Id\Billable;
+use Anikeen\Id\Exceptions\ApiException;
 use Illuminate\Database\Eloquent\Model;

 /**
@@ -199,6 +200,35 @@ class EndpointsTest extends TestCase
        $this->assertSame('POST /api/v1/admin/transactions Bearer app-token', $this->sentCall(1));
    }

+    public function test_billing_portal_links_for_users_use_the_app_token(): void
+    {
+        $link = ['object' => 'billing_portal_link', 'url' => 'https://id.test/billing/portal/01JUSER?signature=x', 'user_id' => '01JUSER', 'flow' => 'invoices', 'group' => 'team-1', 'return_url' => 'https://console.test/billing', 'expires_at' => '2026-11-04T10:15:00+00:00'];
+        $this->respond(201, ['data' => $link]);
+        $this->respond(201, ['data' => $link]);
+
+        $created = app(AnikeenId::class)->createBillingPortalLinkForUser('01JUSER', ['return_url' => 'https://console.test/billing', 'group' => 'team-1', 'flow' => 'invoices']);
+        $url = $this->owner()->appBillingPortalUrl(['flow' => 'payment_method_update']);
+
+        $this->assertSame('billing_portal_link', $created->object);
+        $this->assertSame($link['url'], $url);
+        $this->assertSame('POST /api/v1/client/users/01JUSER/billing-portal Bearer app-token', $this->sentCall(0));
+        $this->assertSame(['return_url' => 'https://console.test/billing', 'group' => 'team-1', 'flow' => 'invoices'], $this->sentJson(0));
+        $this->assertSame('POST /api/v1/client/users/01JUSER/billing-portal Bearer app-token', $this->sentCall(1));
+        $this->assertSame(['flow' => 'payment_method_update'], $this->sentJson(1));
+    }
+
+    public function test_a_refused_billing_portal_link_is_an_api_exception(): void
+    {
+        $this->respond(422, ['message' => 'The return URL has to point to one of the app\'s redirect URIs.', 'errors' => ['return_url' => ['…']]]);
+
+        try {
+            $this->owner()->appBillingPortalUrl(['return_url' => 'https://elsewhere.test']);
+            $this->fail('Expected an ApiException.');
+        } catch (ApiException $e) {
+            $this->assertSame(422, $e->status);
+        }
+    }
+
    public function test_order_preview_maps_the_country_into_the_billing_address(): void
    {
        $this->respond(200, ['data' => ['gross_total' => 11.9]]);
@@ -0,0 +1,57 @@
+<?php
+
+namespace Anikeen\Id\Tests;
+
+use Anikeen\Id\Billable;
+use Anikeen\Id\Enums\SubscriptionStatus;
+use Anikeen\Id\Resources\AppSubscription;
+use Illuminate\Database\Eloquent\Model;
+use PHPUnit\Framework\Attributes\DataProvider;
+
+class SubscriptionStatusTest extends TestCase
+{
+    private const BASE = ['id' => '01JSUB', 'active' => false, 'autorenew' => true, 'cancelled' => false, 'starts_at' => null, 'cancels_at' => null, 'trial_ends_at' => null];
+
+    public static function states(): array
+    {
+        $started = ['starts_at' => '2026-10-01T00:00:00+00:00'];
+
+        return [
+            'draft' => [[], SubscriptionStatus::DRAFT, false],
+            'active' => [['active' => true, ...$started], SubscriptionStatus::ACTIVE, true],
+            'trial' => [['active' => true, 'trial_ends_at' => date(DATE_ATOM, time() + 86400), ...$started], SubscriptionStatus::TRIAL, true],
+            'trial over' => [['active' => true, 'trial_ends_at' => '2026-01-01T00:00:00+00:00', ...$started], SubscriptionStatus::ACTIVE, true],
+            'paused' => [['active' => true, 'autorenew' => false, ...$started], SubscriptionStatus::PAUSED, true],
+            'cancelling' => [['active' => true, 'cancels_at' => '2027-01-01T00:00:00+00:00', ...$started], SubscriptionStatus::CANCELLING, true],
+            'expired' => [['autorenew' => false, ...$started], SubscriptionStatus::EXPIRED, false],
+            'cancelled' => [['autorenew' => false, 'cancelled' => true, ...$started], SubscriptionStatus::CANCELLED, false],
+        ];
+    }
+
+    #[DataProvider('states')]
+    public function test_the_status_follows_the_fields(array $fields, string $status, bool $running): void
+    {
+        $data = [...self::BASE, ...$fields];
+
+        $this->respond(200, ['data' => [$data]]); // subscriptions() loads the list
+        $this->respond(200, ['data' => $data]);
+        $owner = new class extends Model {
+            use Billable;
+        };
+        $owner->anikeen_id_access_token = 'user-token';
+        $subscription = $owner->subscriptions()->find('01JSUB');
+
+        $app = new AppSubscription((object) $data);
+
+        foreach ([$subscription, $app] as $resource) {
+            $this->assertSame($status, $resource->status());
+            $this->assertSame($running, $resource->isActive());
+            $this->assertSame($status === SubscriptionStatus::DRAFT, $resource->isDraft());
+            $this->assertSame($status === SubscriptionStatus::TRIAL, $resource->isTrial());
+            $this->assertSame($status === SubscriptionStatus::PAUSED, $resource->isPaused());
+            $this->assertSame($status === SubscriptionStatus::CANCELLING, $resource->isCancelling());
+            $this->assertSame($status === SubscriptionStatus::EXPIRED, $resource->isExpired());
+            $this->assertSame($status === SubscriptionStatus::CANCELLED, $resource->isCancelled());
+        }
+    }
+}
@@ -0,0 +1,97 @@
+<?php
+
+namespace Anikeen\Id\Tests;
+
+use Anikeen\Id\Billable;
+use Anikeen\Id\Exceptions\ApiException;
+use Anikeen\Id\Exceptions\CollectionException;
+use Anikeen\Id\Exceptions\ConfirmationRequiredException;
+use Anikeen\Id\Exceptions\ResourceException;
+use GuzzleHttp\Exception\ConnectException;
+use GuzzleHttp\Psr7\Request;
+use Illuminate\Database\Eloquent\Model;
+
+class UserApiExceptionsTest extends TestCase
+{
+    private function user(): Model
+    {
+        $user = new class extends Model {
+            use Billable;
+        };
+        $user->anikeen_id_access_token = 'user-token';
+
+        return $user;
+    }
+
+    public function test_a_refused_request_carries_status_and_error_code(): void
+    {
+        $this->respond(200, ['data' => []]); // orders() loads the list
+        $this->respond(422, ['message' => 'The billing address is missing.', 'error' => 'billing_address_missing']);
+
+        try {
+            $this->user()->orders()->create(['items' => []]);
+            $this->fail('Expected an ApiException.');
+        } catch (ApiException $e) {
+            $this->assertInstanceOf(ResourceException::class, $e, 'existing catch (ResourceException) blocks keep working');
+            $this->assertSame(422, $e->status);
+            $this->assertSame(422, $e->getCode());
+            $this->assertSame('billing_address_missing', $e->error);
+            $this->assertSame('The billing address is missing', $e->getMessage());
+            $this->assertFalse($e->isTemporary());
+        }
+    }
+
+    public function test_an_unknown_id_is_not_found(): void
+    {
+        $this->respond(200, ['data' => []]);
+        $this->respond(404, ['message' => 'Not found.']);
+
+        try {
+            $this->user()->orders()->find('01JMISSING');
+            $this->fail('Expected an ApiException.');
+        } catch (ApiException $e) {
+            $this->assertTrue($e->isNotFound());
+            $this->assertNull($e->error);
+        }
+    }
+
+    public function test_a_failed_list_is_an_api_exception_too(): void
+    {
+        $this->respond(503, ['message' => 'Maintenance.']);
+
+        try {
+            $this->user()->invoices();
+            $this->fail('Expected a CollectionException.');
+        } catch (CollectionException $e) {
+            $this->assertInstanceOf(ApiException::class, $e);
+            $this->assertSame(503, $e->status);
+            $this->assertTrue($e->isTemporary());
+        }
+    }
+
+    public function test_no_response_is_temporary_with_status_zero(): void
+    {
+        $this->respond(200, ['data' => []]);
+        $this->http->append(new ConnectException('Connection refused', new Request('GET', 'v1/orders/01J')));
+
+        try {
+            $this->user()->orders()->find('01J');
+            $this->fail('Expected an ApiException.');
+        } catch (ApiException $e) {
+            $this->assertSame(0, $e->status);
+            $this->assertTrue($e->isTemporary());
+            $this->assertInstanceOf(ConnectException::class, $e->getPrevious());
+        }
+    }
+
+    public function test_confirmation_required_stays_its_own_exception(): void
+    {
+        $this->respond(200, ['data' => []]);
+        $this->respond(200, ['data' => ['id' => '01JORDER', 'status' => 'draft']]);
+        $this->respond(403, ['message' => 'Confirm it on Anikeen ID.', 'error' => 'confirmation_required', 'confirmation_url' => 'https://id.test/confirm/01JORDER']);
+
+        $this->expectException(ConfirmationRequiredException::class);
+
+        $this->user()->orders()->find('01JORDER')->checkout();
+    }
+}
@@ -3,6 +3,7 @@
 namespace Anikeen\Id\Tests;

 use Anikeen\Id\Exceptions\SignatureVerificationException;
+use Anikeen\Id\Webhooks\EventType;
 use Anikeen\Id\Webhooks\Webhook;

 class WebhookTest extends TestCase
@@ -53,4 +54,31 @@ class WebhookTest extends TestCase

        Webhook::constructEvent($this->payload, null, $this->secret);
    }
+
+    public function test_a_renewal_carries_the_booked_period(): void
+    {
+        $this->payload = json_encode(['id' => '01JEVT', 'type' => EventType::SUBSCRIPTION_RENEWED, 'created' => time(), 'data' => [
+            'object' => ['id' => '01JSUB', 'status' => 'active'],
+            'period' => ['object' => 'subscription_period', 'subscription_id' => '01JSUB', 'period_start' => '2026-11-01T00:00:00+00:00', 'period_end' => '2026-12-01T00:00:00+00:00', 'periods' => 1, 'first_period' => true, 'unit' => 'month', 'order_id' => '01JORD', 'order_item_id' => '01JITEM', 'items' => [], 'currency_iso' => 'EUR', 'net_amount' => 8],
+        ]]);
+
+        $event = Webhook::constructEvent($this->payload, $this->header(), $this->secret);
+
+        $this->assertSame('subscription.renewed', $event['type']);
+        $this->assertSame('01JORD', $event['data']['period']['order_id']);
+        $this->assertTrue($event['data']['period']['first_period']);
+        $this->assertContains(EventType::SUBSCRIPTION_RENEWED, EventType::all());
+    }
+
+    public function test_a_change_carries_the_previous_attributes(): void
+    {
+        $this->payload = json_encode(['id' => '01JEVT', 'type' => EventType::SUBSCRIPTION_UPDATED, 'created' => time(), 'data' => [
+            'object' => ['id' => '01JSUB', 'price' => 14.99],
+            'previous_attributes' => ['price' => 9.99],
+        ]]);
+
+        $event = Webhook::constructEvent($this->payload, $this->header(), $this->secret);
+
+        $this->assertSame(9.99, $event['data']['previous_attributes']['price']);
+    }
 }
Author	SHA1	Message	Date
Maurice Preuß	ade2970272	Document per-app collective orders and the order's oauth_client_id Collective orders are kept per app on Anikeen ID now: an app's subscriptions are never billed on another app's order, even with the same group. Document oauth_client_id on orders (Order property, app orders) and how legacy orders that billed several apps appear (own lines only, invoice PDF refused with 403 invoice_includes_other_apps).	2026-11-04 23:02:48 +01:00
Maurice Preuß	a54b5fe598	Document trials without a payment method trial_payment_method (TrialPaymentMethod::REQUIRED, the default, or ::OPTIONAL) on app subscriptions, subscriptions and checkout sessions: an optional trial can be confirmed without a payment method and is cancelled at its end if there is still none (cancellation_reason and subscription.cancelled data.reason CancellationReason::TRIAL_ENDED_WITHOUT_PAYMENT_METHOD). subscription.trial_will_end carries data.payment_method_missing.	2026-11-04 22:44:03 +01:00
Maurice Preuß	a68e9ed257	Merge main into feature/uptimr-billing-api	2026-11-04 22:11:16 +01:00
envoyr	0ed6934da3	Merge pull request #16 from anikeen-com/fix/dependabot-alerts Require patched Laravel and php-jwt versions	2026-11-04 22:09:39 +01:00
Maurice Preuß	df7e506a5e	Require patched Laravel and php-jwt versions Raise the minimum versions so installs can no longer resolve releases with known advisories (Dependabot alerts): - laravel/framework / illuminate/*: ^12.69\|^13.0 (TokenGuard auth bypass, CRLF injection in the email rule, signed URL path confusion, debug page XSS). Laravel 11 is end of life and gets no fixes, so support for it is dropped. - firebase/php-jwt: ^7.0 (weak encryption in 6.x). - orchestra/testbench: ^10.0\|^11.0 to match. Tests pass with both the lowest and the highest allowed versions.	2026-11-04 22:05:30 +01:00
Maurice Preuß	7f16155701	Document first_period on subscription.renewed and login-free billing portal links - subscription.renewed is now sent for the first paid period too; data.period.first_period tells it apart (README, EventType, test payload). - Billing portal links need no login, are single use and valid for about 15 minutes: create them on click and redirect right away (README, createBillingPortalLinkForUser(), appBillingPortalUrl()).	2026-11-04 21:57:49 +01:00
Maurice Preuß	35ca9ddd2b	Create billing portal links for users as a trusted app AnikeenId::createBillingPortalLinkForUser() and $user->appBillingPortalUrl() create a short-lived link to a user's billing pages with the app's token (return_url, group, flow), e.g. for a Manage billing button of an app that bills a team owner's account.	2026-11-04 21:27:26 +01:00
Maurice Preuß	e45a871ca7	Let users confirm orders of trusted apps confirm, return_url and metadata on createOrderForUser() and orders created with the user's token: the order stays a draft with a confirmation_url and expires after 24 hours (409 confirmation_expired on checkout). metadata can be changed on a draft with Order::update().	2026-11-04 21:26:47 +01:00
Maurice Preuß	bd56f114da	Read order lines and invoices of app orders Document the items (subscription, period, net amount, discount), invoice and metadata of orders read with the app's token, add AppOrders::invoicePdf() for the invoice PDF and the opt-in subscription.renewed event type with its period data.	2026-11-04 21:25:56 +01:00
Maurice Preuß	db3c50af72	Change running subscriptions AppSubscription::change() changes price, unit, name, description or discount of a running subscription, prorated right away (APPLY_NOW) or from the next period on (APPLY_PERIOD_END, shown as scheduled_change); cancelScheduledChange() drops a scheduled one. Adds the subscription.updated event type and documents proration_not_possible and credit_exceeds_bill.	2026-11-04 21:25:00 +01:00
Maurice Preuß	bf21142f72	Discount subscriptions per billed period discount (label, percent_off or amount_off, duration once, repeating or forever) when creating subscriptions and per subscription of checkout sessions, the discount field on subscriptions and the subscription.discount_ended event type.	2026-11-04 21:24:22 +01:00
Maurice Preuß	5cc1a519c3	Start subscriptions with a free trial trial_days, trial_ends_at and trial_once when creating subscriptions (app and user token) and per subscription of checkout sessions. isTrial() on subscriptions, the subscription.trial_will_end event type, and the trial_already_used error code in the docs.	2026-11-04 21:23:52 +01:00
envoyr	61385df92f	Merge pull request #15 from anikeen-com/feature/user-api-exceptions Throw ApiException for requests with the user's token too	2026-11-04 18:44:38 +01:00
Maurice PreußandClaude Opus 5.5	57ce0b4a79	Throw ApiException for requests with the user's token too Requests with the user's token threw a bare ResourceException with a message like "… for resource [Anikeen\Id\Resources\Order]" and no error code, while app requests threw ApiException. Both throw ApiException now: status (also getCode()), Anikeen ID's error code and message, isNotFound(), isConflict(), isTemporary(). Failed lists throw CollectionException, now a subclass of ApiException. A request without a response (connection refused, timeout) throws ApiException with status 0 instead of a Guzzle exception. ApiException extends ResourceException, so existing catch blocks keep working. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-11-04 18:28:50 +01:00
envoyr	a4345e72ec	Merge pull request #14 from anikeen-com/docs/remove-live-test-hint Document payments end to end, add subscription status helpers	2026-11-04 17:56:25 +01:00
Maurice PreußandClaude Opus 5.5	ce820cd198	Add subscription status helpers status() returns draft, trial, active, paused, cancelling, expired or cancelled (SubscriptionStatus constants), derived from the fields the same way Anikeen ID derives its status, so it also works with older responses. isActive() is true while the subscription runs and is paid. Both Subscription and AppSubscription have them. Document the states. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-11-04 16:15:48 +01:00
Maurice PreußandClaude Opus 5.5	2faccac0f4	Document Stripe test cards on staging Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-11-04 16:09:47 +01:00
Maurice PreußandClaude Opus 5.5	e3e59fb8a4	Document payments end to end Add a Payments guide that follows a typical third-party shop: sign-in scopes, user table and token storage, creating orders and subscriptions, the confirmation and return flow, statuses, prices and VAT, shipments, webhooks with Laravel 11 CSRF exclusion, error handling and testing. Move the trusted-app sections and API authentication after it, add the webhook secret to the config, fix the broken General/Examples snippets and the Scope enum link. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-11-04 16:06:23 +01:00
Maurice PreußandClaude Opus 5.5	26716e7bba	Add CLAUDE.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-11-04 16:00:29 +01:00
Maurice PreußandClaude Opus 5.5	2acbef72c8	Drop the live API test hint from the README The tests use a mocked HTTP client and ignore these variables. Also move the shipping address and shipment docs into README.stub, so composer docs no longer drops them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-11-04 16:00:24 +01:00