@inklok/api-spec 7.8.4 → 7.9.1

package/openapi.yaml

@@ -8,7 +8,7 @@ info:
     Authenticate using an API key or bearer token, then use the resources below to manage
     templates, agreements, documents, and signing. For your first integration, start with
     the Quick Start guide.
-  version: "7.8.4"
+  version: "7.9.1"
   contact:
     name: Inklok API Support
     email: support@inklok.com
@@ -470,6 +470,64 @@ paths:
         '500':
           $ref: '#/components/responses/InternalServerError'
 
+  /me/billing/seats:
+    post:
+      operationId: updateMeBillingSeats
+      summary: Update additional seats for the current account
+      x-internal: true
+      x-visibility: internal
+      description: |
+        Updates the Additional Seat subscription item quantity for the authenticated
+        account's active Paddle-managed Pro or Team subscription.
+      tags:
+        - Me
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MeBillingSeatsUpdateRequest'
+      responses:
+        '200':
+          description: Successfully updated seats
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MeBillingResponse'
+        '202':
+          description: Paddle accepted the seat change and local billing reconciliation was requested
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: false
+                required:
+                  - accountId
+                  - status
+                  - message
+                properties:
+                  accountId:
+                    type: string
+                  status:
+                    type: string
+                    enum: [reconciliation_requested]
+                  message:
+                    type: string
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '502':
+          $ref: '#/components/responses/BadGateway'
+        '503':
+          $ref: '#/components/responses/ServiceUnavailable'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
   /platform/overview:
     get:
       operationId: getPlatformOverview
@@ -708,6 +766,54 @@ paths:
         '500':
           $ref: '#/components/responses/InternalServerError'
 
+  /platform/billing-activity:
+    get:
+      operationId: getPlatformBillingActivity
+      summary: Get Platform billing activity
+      x-visibility: internal
+      description: |
+        Returns normalized billing activity for one account, newest first.
+        Requires an authorized platform administrator.
+        Raw Paddle webhook payloads and payment details are not returned.
+      x-required-global-roles: [PLATFORM_ADMIN]
+      tags:
+        - Platform
+      parameters:
+        - in: query
+          name: accountId
+          required: true
+          schema:
+            type: string
+          description: Billing account ID to inspect.
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 25
+          description: Maximum number of activity rows to return.
+        - in: query
+          name: cursor
+          schema:
+            type: string
+          description: Opaque pagination cursor returned by the previous response.
+      responses:
+        '200':
+          description: Successfully retrieved Platform billing activity
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlatformBillingActivityResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
   /platform/ses:
     get:
       operationId: getPlatformSes
@@ -3787,6 +3893,9 @@ components:
         - nextBilledAt
         - nextExpectedBillingTransition
         - reconciliationRequested
+        - includedSeats
+        - additionalSeats
+        - effectiveSeatLimit
       properties:
         source:
           type: string
@@ -3836,6 +3945,52 @@ components:
           nullable: true
         reconciliationRequested:
           type: boolean
+        includedSeats:
+          type: integer
+          nullable: true
+          minimum: 0
+        additionalSeats:
+          type: integer
+          minimum: 0
+        effectiveSeatLimit:
+          type: integer
+          nullable: true
+          minimum: 0
+
+    MeBillingSeats:
+      type: object
+      additionalProperties: false
+      required:
+        - includedSeats
+        - additionalSeats
+        - effectiveSeatLimit
+        - usedSeats
+      properties:
+        includedSeats:
+          type: integer
+          nullable: true
+          minimum: 0
+        additionalSeats:
+          type: integer
+          minimum: 0
+        effectiveSeatLimit:
+          type: integer
+          nullable: true
+          minimum: 0
+        usedSeats:
+          type: integer
+          nullable: true
+          minimum: 0
+
+    MeBillingSeatsUpdateRequest:
+      type: object
+      additionalProperties: false
+      required:
+        - additionalSeats
+      properties:
+        additionalSeats:
+          type: integer
+          minimum: 0
 
     MeBillingResponse:
       type: object
@@ -3846,6 +4001,7 @@ components:
         - plan
         - subscriptionStatus
         - limits
+        - seats
         - billingSubscription
       properties:
         accountId:
@@ -3861,6 +4017,8 @@ components:
         limits:
           type: object
           additionalProperties: true
+        seats:
+          $ref: '#/components/schemas/MeBillingSeats'
         billingSubscription:
           $ref: '#/components/schemas/MeBillingSubscription'
 
@@ -4801,6 +4959,131 @@ components:
               enum:
                 - peak_minute
                 - daily_capacity
+      generatedAt:
+        type: string
+        format: date-time
+
+    PlatformBillingActivityType:
+      type: string
+      enum:
+        - plan_changed
+        - subscription_status_changed
+        - seats_changed
+        - billing_reconciled
+        - seat_change_failed
+
+    PlatformBillingActivitySource:
+      type: string
+      enum:
+        - paddle_webhook
+        - me_billing
+        - billing_reconciliation
+
+    PlatformBillingActivityItem:
+      type: object
+      required:
+        - accountId
+        - activityId
+        - activityKey
+        - activityType
+        - occurredAt
+        - source
+        - createdAt
+      properties:
+        accountId:
+          type: string
+        activityId:
+          type: string
+        activityKey:
+          type: string
+        activityType:
+          $ref: '#/components/schemas/PlatformBillingActivityType'
+        occurredAt:
+          type: string
+          format: date-time
+        source:
+          $ref: '#/components/schemas/PlatformBillingActivitySource'
+        actorUserId:
+          type: string
+          nullable: true
+        requestId:
+          type: string
+          nullable: true
+        paddleEventId:
+          type: string
+          nullable: true
+        paddleSubscriptionId:
+          type: string
+          nullable: true
+        oldPlan:
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/Plan'
+        newPlan:
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/Plan'
+        oldSubscriptionStatus:
+          type: string
+          nullable: true
+        newSubscriptionStatus:
+          type: string
+          nullable: true
+        oldAdditionalSeats:
+          type: integer
+          nullable: true
+          minimum: 0
+        newAdditionalSeats:
+          type: integer
+          nullable: true
+          minimum: 0
+        oldEffectiveSeatLimit:
+          type: integer
+          nullable: true
+          minimum: 0
+        newEffectiveSeatLimit:
+          type: integer
+          nullable: true
+          minimum: 0
+        attemptedAdditionalSeats:
+          type: integer
+          nullable: true
+          minimum: 0
+        attemptedEffectiveSeatLimit:
+          type: integer
+          nullable: true
+          minimum: 0
+        errorCode:
+          type: string
+          nullable: true
+        errorCategory:
+          type: string
+          nullable: true
+        createdAt:
+          type: string
+          format: date-time
+
+    PlatformBillingActivityResponse:
+      type: object
+      required:
+        - accountId
+        - items
+        - count
+        - nextCursor
+        - generatedAt
+      properties:
+        accountId:
+          type: string
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/PlatformBillingActivityItem'
+        count:
+          type: integer
+          minimum: 0
+        nextCursor:
+          type: string
+          nullable: true
         generatedAt:
           type: string
           format: date-time

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inklok/api-spec",
-  "version": "7.8.4",
+  "version": "7.9.1",
   "description": "Canonical OpenAPI specification for the Inklok public API.",
   "main": "openapi.yaml",
   "license": "MIT",