@saasicat/spec 1.0.0-rc.24 → 1.0.0-rc.26

package/admin-api.openapi.yaml

@@ -29,7 +29,7 @@ openapi: 3.1.0
 
 info:
     title: SaaS Platform SuperAdmin API
-    version: 1.0.0-rc.24
+    version: 1.0.0-rc.26
     description: |
         Read and write operations for platform administration:
         tenants, users, subscriptions, promo codes, audit log,
@@ -387,6 +387,240 @@ paths:
                 '404':
                     description: No tenant with this slug (`TENANT_NOT_FOUND`)
 
+    /invoices/{id}/document:
+        parameters:
+            - name: id
+              in: path
+              required: true
+              description: The invoice's id
+              schema: { type: string }
+        get:
+            tags: [subscriptions]
+            summary: The document an invoice was issued as
+            description: >-
+                Served where the platform keeps invoices
+                (`tenantBilling.chargeJournal.invoices`) and shows tenants
+                (`adminResources`); the manifest announces it as
+                `invoices.read`. Answers the file archived for the invoice,
+                checked against the checksum recorded when it was rendered —
+                never a new rendering. Its media type is the one the renderer
+                gave, a PDF for a ZUGFeRD invoice.
+            responses:
+                '200':
+                    description: The archived file, as an attachment
+                    headers:
+                        Content-Disposition:
+                            description: >-
+                                `attachment; filename="…"`, the renderer's file
+                                name kept to letters, digits, `.`, `_` and `-`
+                            schema: { type: string }
+                    content:
+                        application/pdf:
+                            schema: { type: string, format: binary }
+                '404':
+                    description: No invoice with this id (`SUBSCRIPTION_INVOICE_NOT_FOUND`)
+                '409':
+                    description: >-
+                        The invoice still waits for its document
+                        (`SUBSCRIPTION_INVOICE_DOCUMENT_NOT_ARCHIVED`), or its
+                        archived file does not match the recorded checksum and
+                        is not handed out (`SUBSCRIPTION_INVOICE_DOCUMENT_MISMATCH`)
+
+    /tenants/{slug}/subscriber:
+        parameters:
+            - $ref: '#/components/parameters/TenantSlug'
+        get:
+            tags: [subscriptions]
+            summary: The tenant's subscriber, its tax details and what holds its next contract back
+            description: >-
+                Served where the platform keeps subscribers and shows tenants
+                (`adminResources`); the manifest announces it as
+                `subscribers.read`. The standing is computed when it is read,
+                and only where a tax adapter decides; elsewhere `readiness` is
+                null.
+            responses:
+                '200':
+                    description: The subscriber, or none
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/AdminTenantSubscriber' }
+                '404':
+                    description: No tenant with this slug (`TENANT_NOT_FOUND`)
+
+    /tenants/{slug}/subscriber/history:
+        parameters:
+            - $ref: '#/components/parameters/TenantSlug'
+        get:
+            tags: [subscriptions]
+            summary: Every correction, change of country or business status, and check of the subscriber, the latest first
+            description: >-
+                Served beside `/tenants/{slug}/subscriber`; the manifest
+                announces it as `subscribers.correct`. A correction that gives
+                another VAT number is named once, as the correction it was. Empty
+                for a tenant without a subscriber.
+            responses:
+                '200':
+                    description: The history
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [entries]
+                                properties:
+                                    entries:
+                                        type: array
+                                        items:
+                                            $ref: '#/components/schemas/AdminSubscriberHistoryEntry'
+                '404':
+                    description: No tenant with this slug (`TENANT_NOT_FOUND`)
+
+    /tenants/{slug}/subscriber/identity:
+        parameters:
+            - $ref: '#/components/parameters/TenantSlug'
+        post:
+            tags: [subscriptions]
+            summary: Correct the legal identity of the tenant's subscriber
+            description: >-
+                A correction of the same legal entity — a field left out keeps
+                its value, `null` clears a tax identifier — recorded with the
+                values it replaced, the reason and who made it. `kind` is the
+                operator's declaration: a takeover by another entity is refused
+                (`SUBSCRIBER_TAKEOVER_IS_A_TRANSFER`). Where a tax adapter
+                decides and the correction gives another VAT number, that
+                number is checked right after and the check recorded, whatever
+                it found; the answer says how it went.
+            x-mfa-required: true
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [kind, reason]
+                            properties:
+                                kind: { type: string, enum: [correction, takeover] }
+                                legalName: { type: string }
+                                vatId: { type: string, nullable: true }
+                                taxNumber: { type: string, nullable: true }
+                                reason: { type: string, maxLength: 500 }
+            responses:
+                '200':
+                    description: The subscriber as it now stands, and the check its new number got
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/AdminSubscriberCorrected' }
+                '404':
+                    description: No tenant with this slug (`TENANT_NOT_FOUND`)
+                '409':
+                    description: The tenant has no subscriber (`SUBSCRIBER_REQUIRED`)
+                '422':
+                    description: >-
+                        A takeover, no reason, or a correction that changes
+                        nothing (`SUBSCRIBER_TAKEOVER_IS_A_TRANSFER`,
+                        `SUBSCRIBER_CORRECTION_REASON_REQUIRED`,
+                        `SUBSCRIBER_CORRECTION_CHANGES_NOTHING`)
+
+    /tenants/{slug}/subscriber/business-status:
+        parameters:
+            - $ref: '#/components/parameters/TenantSlug'
+        post:
+            tags: [subscriptions]
+            summary: Record whether the tenant's subscriber acts as a business, and why
+            description: >-
+                Recorded as a change of the tax origin with its reason and who
+                made it; it applies from the next contract. Setting the status it
+                has records nothing.
+            x-mfa-required: true
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [business, reason]
+                            properties:
+                                business: { type: boolean, nullable: true }
+                                reason: { type: string, maxLength: 500 }
+            responses:
+                '200':
+                    description: The subscriber as it now stands
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/AdminSubscriberCorrected' }
+                '404':
+                    description: No tenant with this slug (`TENANT_NOT_FOUND`)
+                '409':
+                    description: The tenant has no subscriber (`SUBSCRIBER_REQUIRED`)
+                '422':
+                    description: No reason (`SUBSCRIBER_BUSINESS_STATUS_REASON_REQUIRED`)
+
+    /tenants/{slug}/subscriber/vat-id-check:
+        parameters:
+            - $ref: '#/components/parameters/TenantSlug'
+        post:
+            tags: [subscriptions]
+            summary: Check the VAT number the tenant's subscriber holds, again
+            description: >-
+                Asks the service the tax adapter names and records a completed
+                check, valid or not; a check that does not complete records
+                nothing and says why. No second factor: nothing is entered, and
+                the answer is the service's.
+            responses:
+                '200':
+                    description: The subscriber as it now stands, and what the check found
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/AdminSubscriberCorrected' }
+                '404':
+                    description: No tenant with this slug (`TENANT_NOT_FOUND`)
+                '409':
+                    description: >-
+                        The tenant has no subscriber, or no tax adapter names a
+                        service (`SUBSCRIBER_REQUIRED`, `TAX_VAT_ID_CHECK_NOT_AVAILABLE`)
+                '422':
+                    description: The subscriber holds no VAT number (`SUBSCRIBER_VAT_ID_MISSING`)
+
+    /subscribers/attention:
+        get:
+            tags: [subscriptions]
+            summary: Which of these tenants hold their subscriber back from its next contract
+            description: >-
+                Served beside `/tenants/{slug}/subscriber`; the manifest
+                announces `subscribers.attention` only where a tax adapter
+                decides, and without one the answer is always empty. A tenant
+                whose subscriber is ready, and one without a subscriber, are
+                left out.
+            parameters:
+                - name: tenantId
+                  in: query
+                  description: The tenants of the page shown; repeat the parameter for each.
+                  schema:
+                      type: array
+                      maxItems: 200
+                      items: { type: string, minLength: 1 }
+                  style: form
+                  explode: true
+            responses:
+                '200':
+                    description: The tenants held back, each with why
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [attention]
+                                properties:
+                                    attention:
+                                        type: array
+                                        items:
+                                            type: object
+                                            required: [tenantId, readiness]
+                                            properties:
+                                                tenantId: { type: string }
+                                                readiness:
+                                                    $ref: '#/components/schemas/SubscriberReadiness'
+                '400':
+                    description: More than 200 tenants, or an empty tenant id
+
     # ────────────────────────────────────────────────────────
     # Users
     # ────────────────────────────────────────────────────────
@@ -812,8 +1046,9 @@ paths:
                                         id: { type: string }
                                         tenant:
                                             type: object
-                                            required: [slug, name]
+                                            required: [id, slug, name]
                                             properties:
+                                                id: { type: string }
                                                 slug: { type: string }
                                                 name: { type: string }
                                         plan: { type: string }
@@ -1084,6 +1319,203 @@ paths:
                                 type: array
                                 items: { $ref: '#/components/schemas/VersionRetirement' }
 
+    # Served where the manifest carries the capability `bundleVersions.retire`. The bookings
+    # on an add-on version no longer on sale continue on a version of the same add-on on
+    # sale, each at the first end of its own period at least three calendar months after
+    # its notice reached the subscriber, and may be cancelled without their minimum term
+    # until then. Where the operator's terms are not confirmed to allow it, both routes
+    # refuse with `RETIREMENT_TERMS_NOT_CONFIRMED` before reading anything.
+
+    /catalog/bundle-versions/{id}/retirement:
+        parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
+        get:
+            tags: [catalog]
+            summary: What retiring the add-on version for its running bookings would do now
+            parameters:
+                - name: replacement
+                  in: query
+                  required: true
+                  description: The version of the same add-on the bookings continue on
+                  schema: { type: string, format: uuid }
+            responses:
+                '200':
+                    description: >-
+                        Which bookings it reaches and when, which it does not and why, and every
+                        blocker the announcement would refuse with
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/BundleRetirementPreview' }
+                '404':
+                    description: Either version does not exist (`BUNDLE_VERSION_NOT_FOUND`)
+                '422':
+                    description: >-
+                        The terms are not confirmed (`RETIREMENT_TERMS_NOT_CONFIRMED`), or the
+                        replacement is the version itself (`RETIREMENT_REPLACEMENT_IS_RETIRED`)
+        post:
+            tags: [catalog]
+            summary: Announce the add-on retirement to every booking it reaches
+            description: >-
+                The announcement and one notice per booking are recorded in one transaction,
+                then handed to the application's `SubscriptionNoticePort` as
+                `bundle-version-retired`; a notice that cannot be sent now is sent by the next
+                run. Audited as BUNDLE_VERSION_RETIRE.
+            x-mfa-required: true
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema: { $ref: '#/components/schemas/BundleRetirementAnnouncement' }
+            responses:
+                '201':
+                    description: Announced
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/BundleRetirementAnnounced' }
+                '409':
+                    description: >-
+                        The bookings it reaches are no longer the ones named
+                        (`RETIREMENT_PREVIEW_CHANGED`); the body carries the preview as it stands
+                '422':
+                    description: >-
+                        The first blocker the preview reports (`BUNDLE_RETIREMENT_*`,
+                        `RETIREMENT_WITHIN_TWELVE_MONTHS`), with every blocker beside it
+
+    /catalog/bundle-version-retirements:
+        get:
+            tags: [catalog]
+            summary: Every add-on retirement announced, the most recent first
+            responses:
+                '200':
+                    description: List, each with how far it has come over the bookings it reached
+                    content:
+                        application/json:
+                            schema:
+                                type: array
+                                items: { $ref: '#/components/schemas/BundleVersionRetirement' }
+
+    # ── Feature withdrawals ──
+    #
+    # Served where the manifest carries the capability `features.withdraw`: where the
+    # installation can list everybody a withdrawal reaches. A feature withdrawn for a reason
+    # outside the platform — an external service stopped, a law changed — is granted to
+    # nobody from the date named until the withdrawal is lifted. The subscriptions holding
+    # it when it is announced are told at once; each line is reduced by the amount named
+    # for its plan or add-on and rhythm, and each may end at once while it is withdrawn.
+
+    /feature-withdrawals:
+        get:
+            tags: [catalog]
+            summary: Every withdrawal, the most recently announced first
+            responses:
+                '200':
+                    description: List, each with how many it reached, told and ended at once
+                    content:
+                        application/json:
+                            schema:
+                                type: array
+                                items: { $ref: '#/components/schemas/FeatureWithdrawal' }
+        post:
+            tags: [catalog]
+            summary: Withdraw a feature from every subscription that holds it
+            description: >-
+                The withdrawal and one notice per subscription are recorded in one transaction,
+                then handed to the application's `SubscriptionNoticePort` as `feature-withdrawn`;
+                a notice that cannot be sent now is sent by the next run. The reductions are
+                written into each subscription's contract. Audited as FEATURE_WITHDRAW.
+            x-mfa-required: true
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema: { $ref: '#/components/schemas/FeatureWithdrawalAnnouncement' }
+            responses:
+                '201':
+                    description: Announced
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/FeatureWithdrawalAnnounced' }
+                '404':
+                    description: >-
+                        Not offered here: the stores cannot list everybody a withdrawal reaches
+                        (`FEATURE_WITHDRAWAL_UNAVAILABLE`)
+                '409':
+                    description: >-
+                        The subscriptions it reaches are no longer the ones named
+                        (`FEATURE_WITHDRAWAL_PREVIEW_CHANGED`, with the preview as it stands), or
+                        another withdrawal of the feature landed first (`FEATURE_WITHDRAWAL_OPEN`)
+                '422':
+                    description: >-
+                        An unknown feature (`FEATURE_WITHDRAWAL_FEATURE_UNKNOWN`), a date already
+                        past (`FEATURE_WITHDRAWAL_DATE_IN_PAST`), a reduction that names nothing it
+                        reaches, is named twice or exceeds the lowest price it reduces
+                        (`FEATURE_WITHDRAWAL_REDUCTION_*`), or the first blocker the preview reports
+
+    /feature-withdrawals/preview:
+        get:
+            tags: [catalog]
+            summary: What withdrawing the feature from the date would do now
+            parameters:
+                - name: featureKey
+                  in: query
+                  required: true
+                  schema: { type: string }
+                - name: effectiveFrom
+                  in: query
+                  required: false
+                  description: ISO-8601; now where left out
+                  schema: { type: string, format: date-time }
+            responses:
+                '200':
+                    description: >-
+                        Whom it reaches with which lines, whom it does not and why, the plans and
+                        add-ons a reduction may be named for, and every blocker
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/FeatureWithdrawalPreview' }
+                '404':
+                    description: Not offered here (`FEATURE_WITHDRAWAL_UNAVAILABLE`)
+                '422':
+                    description: >-
+                        An unknown feature (`FEATURE_WITHDRAWAL_FEATURE_UNKNOWN`), or a date already
+                        past (`FEATURE_WITHDRAWAL_DATE_IN_PAST`)
+
+    /feature-withdrawals/{id}/lift:
+        parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
+        post:
+            tags: [catalog]
+            summary: Lift a withdrawal from a date
+            description: >-
+                From the date the feature is granted again, and the reduction and the right to end
+                at once end; every subscription it reached that still runs is told as
+                `feature-withdrawal-lifted`. Audited as FEATURE_WITHDRAWAL_LIFT.
+            x-mfa-required: true
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            properties:
+                                liftedFrom:
+                                    type: string
+                                    format: date-time
+                                    description: ISO-8601; now where left out
+            responses:
+                '201':
+                    description: Lifted
+                    content:
+                        application/json:
+                            schema: { $ref: '#/components/schemas/FeatureWithdrawalLifted' }
+                '404':
+                    description: No withdrawal has that id (`FEATURE_WITHDRAWAL_NOT_FOUND`)
+                '409':
+                    description: >-
+                        Lifted already (`FEATURE_WITHDRAWAL_ALREADY_LIFTED`, with its date), or nobody
+                        it reaches told of it yet, telling them having failed just now
+                        (`FEATURE_WITHDRAWAL_NOT_TOLD_YET`)
+                '422':
+                    description: A date already past (`FEATURE_WITHDRAWAL_LIFT_IN_PAST`)
+
     # ── Bundles ──
     /catalog/bundles:
         get:
@@ -2114,6 +2546,327 @@ components:
                 told: { type: integer, description: 'Notices sent at once' }
                 failed: { type: integer, description: 'Notices the next run sends' }
 
+        FeatureWithdrawalReduction:
+            type: object
+            required: [kind, key, billingCycle, amountNet]
+            properties:
+                kind: { type: string, enum: [plan, bundle] }
+                key: { type: string, description: 'The plan key, or the add-on key' }
+                billingCycle: { type: string, enum: [MONTHLY, YEARLY] }
+                amountNet:
+                    type: number
+                    description: 'Net, per whole period of the rhythm, to the cent'
+
+        FeatureWithdrawalAnnouncement:
+            type: object
+            required: [featureKey, reason, reductions, subscriptionIds]
+            properties:
+                featureKey: { type: string }
+                reason: { type: string, description: 'Shown to the subscribers as written' }
+                effectiveFrom:
+                    { type: string, format: date-time, description: 'Now where left out' }
+                reductions:
+                    type: array
+                    items: { $ref: '#/components/schemas/FeatureWithdrawalReduction' }
+                subscriptionIds:
+                    type: array
+                    description: 'The subscriptions the operator was shown in the preview'
+                    items: { type: string }
+
+        FeatureWithdrawalRow:
+            type: object
+            required:
+                [
+                    id,
+                    featureKey,
+                    reason,
+                    effectiveFrom,
+                    liftedFrom,
+                    reductions,
+                    announcedAt,
+                    announcedBy,
+                    liftedAt,
+                    liftedBy,
+                    toldAt,
+                ]
+            properties:
+                id: { type: string }
+                featureKey: { type: string }
+                reason: { type: string }
+                effectiveFrom: { type: string, format: date-time }
+                liftedFrom: { type: [string, 'null'], format: date-time }
+                reductions:
+                    type: array
+                    items: { $ref: '#/components/schemas/FeatureWithdrawalReduction' }
+                announcedAt: { type: string, format: date-time }
+                announcedBy:
+                    { type: string, description: 'An actor tag, as the audit log writes it' }
+                liftedAt: { type: [string, 'null'], format: date-time }
+                liftedBy: { type: [string, 'null'] }
+                toldAt:
+                    type: [string, 'null']
+                    format: date-time
+                    description: >-
+                        When the subscriptions it reaches were told; null until then — the
+                        quarter-hourly run tells a withdrawal still null.
+
+        FeatureWithdrawal:
+            allOf:
+                - $ref: '#/components/schemas/FeatureWithdrawalRow'
+                - type: object
+                  required: [featureLabel, progress]
+                  properties:
+                      featureLabel: { type: string }
+                      progress:
+                          type: object
+                          required: [reached, told, endedAtOnce]
+                          properties:
+                              reached: { type: integer, description: 'Subscriptions it reached' }
+                              told:
+                                  type: integer
+                                  description: 'Of those, the ones whose notice reached somebody'
+                              endedAtOnce:
+                                  type: integer
+                                  description: 'Subscriptions and bookings ended at once under it'
+
+        FeatureWithdrawalAnnounced:
+            type: object
+            required: [withdrawal, told, failed]
+            properties:
+                withdrawal: { $ref: '#/components/schemas/FeatureWithdrawalRow' }
+                told: { type: integer, description: 'Notices sent at once' }
+                failed: { type: integer, description: 'Notices the next run sends' }
+
+        FeatureWithdrawalLifted:
+            type: object
+            required: [withdrawal, told, failed]
+            properties:
+                withdrawal: { $ref: '#/components/schemas/FeatureWithdrawalRow' }
+                told: { type: integer, description: 'Notices sent at once' }
+                failed: { type: integer, description: 'Notices the next run sends' }
+
+        FeatureWithdrawalPreview:
+            type: object
+            required: [feature, effectiveFrom, asOf, reached, skipped, targets, blockers]
+            properties:
+                feature:
+                    type: object
+                    required: [key, label]
+                    properties:
+                        key: { type: string }
+                        label: { type: string }
+                effectiveFrom: { type: string, description: 'ISO-8601' }
+                asOf: { type: string, description: 'ISO-8601: the moment it is computed for' }
+                reached:
+                    type: array
+                    items:
+                        type: object
+                        required: [tenantId, subscriptionId, status, lines, specialTerms]
+                        properties:
+                            tenantId: { type: string }
+                            subscriptionId: { type: string }
+                            status: { type: string }
+                            lines:
+                                type: array
+                                items:
+                                    type: object
+                                    required:
+                                        [
+                                            line,
+                                            key,
+                                            label,
+                                            subscriptionBundleId,
+                                            billingCycle,
+                                            priceNet,
+                                        ]
+                                    properties:
+                                        line: { type: string, enum: [plan, bundle] }
+                                        key: { type: string }
+                                        label: { type: string }
+                                        subscriptionBundleId: { type: [string, 'null'] }
+                                        billingCycle: { type: string, enum: [MONTHLY, YEARLY] }
+                                        priceNet: { type: [number, 'null'] }
+                            specialTerms:
+                                type: boolean
+                                description: 'Holds the feature through special terms, and no line'
+                skipped:
+                    type: array
+                    items:
+                        type: object
+                        required: [tenantId, subscriptionId, reason]
+                        properties:
+                            tenantId: { type: string }
+                            subscriptionId: { type: string }
+                            reason: { type: string, enum: [ends-before] }
+                targets:
+                    type: array
+                    description: 'Each plan and add-on in a rhythm a reduction may be named for'
+                    items:
+                        type: object
+                        required: [kind, key, label, billingCycle, lines, lowestPriceNet]
+                        properties:
+                            kind: { type: string, enum: [plan, bundle] }
+                            key: { type: string }
+                            label: { type: string }
+                            billingCycle: { type: string, enum: [MONTHLY, YEARLY] }
+                            lines: { type: integer }
+                            lowestPriceNet: { type: [number, 'null'] }
+                blockers:
+                    type: array
+                    description: 'Empty where it may be announced as it stands'
+                    items:
+                        type: object
+                        required: [code, message, params]
+                        properties:
+                            code: { type: string, description: 'FEATURE_WITHDRAWAL_*' }
+                            message: { type: string }
+                            params: { type: object }
+
+        RetiredBundleVersionRef:
+            type: object
+            required: [bundleVersionId, bundleKey, version]
+            properties:
+                bundleVersionId: { type: string }
+                bundleKey: { type: string }
+                version: { type: integer }
+
+        BundleVersionSide:
+            description: >-
+                An add-on version as the subscribers compare it, at its own prices; each booking
+                is told the prices beside its plan. A price of null is a rhythm it is not sold in
+            allOf:
+                - $ref: '#/components/schemas/RetiredBundleVersionRef'
+                - type: object
+                  required: [label, features, quotas, monthlyNet, yearlyNet]
+                  properties:
+                      label: { type: string }
+                      features: { type: array, items: { type: string } }
+                      quotas: { type: object, additionalProperties: { type: number } }
+                      monthlyNet: { type: [number, 'null'] }
+                      yearlyNet: { type: [number, 'null'] }
+
+        BundleRetirementPreview:
+            type: object
+            required: [retired, replacement, changes, asOf, reached, skipped, blockers]
+            properties:
+                retired: { $ref: '#/components/schemas/BundleVersionSide' }
+                replacement: { $ref: '#/components/schemas/BundleVersionSide' }
+                changes:
+                    type: array
+                    description: 'Every difference at the two versions own prices'
+                    items: { type: object }
+                asOf: { type: string, description: 'ISO-8601: the moment it is computed for' }
+                reached:
+                    type: array
+                    items:
+                        type: object
+                        required:
+                            [
+                                tenantId,
+                                subscriptionId,
+                                subscriptionBundleId,
+                                planKey,
+                                planCycle,
+                                billingCycle,
+                                effectiveAt,
+                                lastDayToCancel,
+                                reachedRecently,
+                            ]
+                        properties:
+                            tenantId: { type: string }
+                            subscriptionId: { type: string }
+                            subscriptionBundleId: { type: string }
+                            planKey: { type: string, description: 'The plan beside it at the date' }
+                            planCycle: { type: string }
+                            billingCycle: { type: string, description: 'The booking rhythm' }
+                            effectiveAt:
+                                { type: string, description: 'ISO-8601: an end of its period' }
+                            lastDayToCancel:
+                                { type: string, description: 'ISO date, UTC: the day before' }
+                            reachedRecently:
+                                {
+                                    type: boolean,
+                                    description: 'Its subscription was reached by a retirement within twelve months',
+                                }
+                skipped:
+                    type: array
+                    items:
+                        type: object
+                        required: [tenantId, subscriptionId, subscriptionBundleId, reason]
+                        properties:
+                            tenantId: { type: string }
+                            subscriptionId: { type: string }
+                            subscriptionBundleId: { type: string }
+                            reason:
+                                {
+                                    type: string,
+                                    enum:
+                                        [
+                                            ended,
+                                            cancelled-before,
+                                            changes-before,
+                                            no-term,
+                                            already-told,
+                                        ],
+                                }
+                blockers:
+                    type: array
+                    description: 'Empty where it may be announced as it stands'
+                    items:
+                        type: object
+                        required: [code, message, params]
+                        properties:
+                            code: { type: string, description: 'BUNDLE_RETIREMENT_*, RETIREMENT_*' }
+                            message: { type: string }
+                            params: { type: object }
+
+        BundleRetirementAnnouncement:
+            type: object
+            required: [replacementBundleVersionId, subscriptionBundleIds]
+            properties:
+                replacementBundleVersionId: { type: string, format: uuid }
+                subscriptionBundleIds:
+                    type: array
+                    description: 'The bookings the operator was shown in the preview'
+                    items: { type: string }
+
+        BundleVersionRetirementRecord:
+            type: object
+            required: [id, retired, replacement, announcedAt, announcedBy]
+            properties:
+                id: { type: string }
+                retired: { $ref: '#/components/schemas/RetiredBundleVersionRef' }
+                replacement: { $ref: '#/components/schemas/RetiredBundleVersionRef' }
+                announcedAt: { type: string }
+                announcedBy: { type: string }
+
+        BundleVersionRetirement:
+            description: 'An add-on announcement as the list answers it, with how far it has come'
+            allOf:
+                - $ref: '#/components/schemas/BundleVersionRetirementRecord'
+                - type: object
+                  required: [progress]
+                  properties:
+                      progress:
+                          type: object
+                          description: 'Counted over the bookings it reached'
+                          required: [moved, waiting, overdue, ended, notTold, reminded]
+                          properties:
+                              moved: { type: integer }
+                              waiting: { type: integer }
+                              overdue: { type: integer }
+                              ended: { type: integer }
+                              notTold: { type: integer }
+                              reminded: { type: integer }
+
+        BundleRetirementAnnounced:
+            type: object
+            required: [retirement, told, failed]
+            properties:
+                retirement: { $ref: '#/components/schemas/BundleVersionRetirementRecord' }
+                told: { type: integer, description: 'Notices sent at once' }
+                failed: { type: integer, description: 'Notices the next run sends' }
+
         CatalogMarketingProjectionUpdate:
             type: object
             description: 'Partial update of a marketing projection'
@@ -2432,6 +3185,139 @@ components:
                                     contract was concluded; null where that line
                                     cannot be read.
 
+        SubscriberReadiness:
+            type: object
+            description: >-
+                Whether a subscriber can be given its next contract where a tax
+                adapter decides: the empty fields of the address an invoice
+                names, and the adapter's sentence where it supports no
+                treatment for the subscriber as it stands.
+            required: [ready, missing, taxRefusal]
+            properties:
+                ready: { type: boolean }
+                missing:
+                    type: array
+                    items:
+                        type: string
+                        enum: [addressLine1, postalCode, city, country]
+                taxRefusal:
+                    type: string
+                    nullable: true
+
+        AdminTenantSubscriber:
+            type: object
+            required: [subscriber, readiness]
+            properties:
+                subscriber:
+                    type: object
+                    nullable: true
+                    description: Null for a tenant that has no subscriber.
+                    required:
+                        [
+                            id,
+                            customerNumber,
+                            legalName,
+                            addressLine1,
+                            addressLine2,
+                            postalCode,
+                            city,
+                            country,
+                            business,
+                            vatId,
+                            vatIdValidated,
+                            taxNumber,
+                            migrated,
+                        ]
+                    properties:
+                        id: { type: string }
+                        customerNumber: { type: string }
+                        legalName: { type: string }
+                        addressLine1: { type: string, nullable: true }
+                        addressLine2: { type: string, nullable: true }
+                        postalCode: { type: string, nullable: true }
+                        city: { type: string, nullable: true }
+                        country: { type: string, nullable: true }
+                        business: { type: boolean, nullable: true }
+                        vatId: { type: string, nullable: true }
+                        vatIdValidated:
+                            type: boolean
+                            description: Whether the check that counts for the VAT id found it valid.
+                        taxNumber: { type: string, nullable: true }
+                        migrated:
+                            type: boolean
+                            description: Created from the application's own tenant record.
+                readiness:
+                    nullable: true
+                    description: Null where no tax adapter decides, or the tenant has no subscriber.
+                    allOf:
+                        - $ref: '#/components/schemas/SubscriberReadiness'
+
+        AdminVatIdCheckOutcome:
+            description: >-
+                A check of a VAT number as the operator is shown it — what the
+                service found, or why the check did not complete.
+            oneOf:
+                - type: object
+                  required: [completed, valid, checkedAt, service, counts]
+                  properties:
+                      completed: { type: boolean, enum: [true] }
+                      valid: { type: boolean }
+                      checkedAt: { type: string, format: date-time }
+                      service: { type: string }
+                      counts:
+                          type: boolean
+                          description: Whether it is the check that counts for the number held now.
+                - type: object
+                  required: [completed, reason]
+                  properties:
+                      completed: { type: boolean, enum: [false] }
+                      reason: { type: string }
+
+        AdminSubscriberCorrected:
+            type: object
+            required: [subscriber, vatIdCheck]
+            properties:
+                subscriber: { $ref: '#/components/schemas/AdminTenantSubscriber' }
+                vatIdCheck:
+                    nullable: true
+                    description: The check a VAT number got, where one was made.
+                    allOf:
+                        - $ref: '#/components/schemas/AdminVatIdCheckOutcome'
+
+        AdminSubscriberHistoryEntry:
+            description: One correction, change of the tax origin, or check of the VAT number.
+            oneOf:
+                - type: object
+                  required: [kind, at, by, previous, corrected, reason]
+                  properties:
+                      kind: { type: string, enum: [identity-corrected] }
+                      at: { type: string, format: date-time }
+                      by: { type: string }
+                      previous: { type: object, additionalProperties: true }
+                      corrected: { type: object, additionalProperties: true }
+                      reason: { type: string }
+                - type: object
+                  required: [kind, at, by, previous, changed, reason]
+                  properties:
+                      kind: { type: string, enum: [tax-origin-changed] }
+                      at: { type: string, format: date-time }
+                      by: { type: string }
+                      previous: { type: object, additionalProperties: true }
+                      changed: { type: object, additionalProperties: true }
+                      reason:
+                          type: string
+                          nullable: true
+                          description: Null for a change of the country with the contact details.
+                - type: object
+                  required: [kind, at, vatId, valid, service, counts]
+                  properties:
+                      kind: { type: string, enum: [vat-id-checked] }
+                      at: { type: string, format: date-time }
+                      vatId: { type: string }
+                      valid: { type: boolean }
+                      service: { type: string }
+                      counts: { type: boolean }
+
         # ────────── User ──────────
         AdminUserRow:
             type: object