payments-ai Subscriptions API

openapi: 3.2.0
info:
  title: Payments AI MoR Merchant Public Subscriptions API
  version: 1.0.0
  description: Merchant Public API, partner onboarding, and buyer checkout endpoints. Authenticate every call with a Merchant API Key (pai_test_* / pai_live_*). The same key reaches its own merchant resources and those of any sub-merchant it has onboarded via POST /v1/public-api/merchants.
servers:
- url: https://sandbox.mor.payments.ai/api
  description: Sandbox API
tags:
- name: Subscriptions
paths:
  /v1/public-api/merchants/{merchantId}/subscriptions:
    get:
      operationId: PublicApiSubscriptions_listSubscriptions
      description: List the merchant's subscriptions, newest first. Unknown query parameters, including camelCase spellings of the filters, are rejected with 400. `merchantId` must be your own merchant or a sub-merchant you created; any other id returns 403.
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
          format: int32
          default: 1
        explode: false
      - name: limit
        in: query
        required: false
        description: At most 200.
        schema:
          type: integer
          format: int32
          default: 20
        explode: false
      - name: customer_id
        in: query
        required: false
        description: Return only this customer's subscriptions.
        schema:
          type: string
        explode: false
      - name: status
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/PublicApiSubscriptionStatus'
        explode: false
      - name: order_id
        in: query
        required: false
        description: Return only the subscriptions started by this order.
        schema:
          type: string
        explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiSubscriptionListResponse'
      summary: List subscriptions
      tags:
      - Subscriptions
  /v1/public-api/merchants/{merchantId}/subscriptions/{subscriptionId}:
    get:
      operationId: PublicApiSubscriptions_getSubscription
      description: Read one subscription. 404 `subscription.not_found` when it does not exist or belongs to another merchant. `merchantId` must be your own merchant or a sub-merchant you created; any other id returns 403.
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: subscriptionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiSubscriptionResponse'
      summary: Get subscription
      tags:
      - Subscriptions
components:
  schemas:
    PublicApiSubscriptionStatus:
      type: string
      enum:
      - active
      - trialing
      - canceling
      - inactive
      description: '`active` renews at the period end. `trialing` is in a free trial. `canceling` keeps access until the period end and then ends. `inactive` has ended.'
    PaginationMeta:
      type: object
      required:
      - totalRecords
      - totalPages
      - currentPage
      - limit
      properties:
        totalRecords:
          type: integer
          format: int32
        totalPages:
          type: integer
          format: int32
        currentPage:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
    PublicApiSubscriptionListResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PublicApiSubscriptionResponse'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    PublicApiSubscriptionResponse:
      type: object
      required:
      - id
      - status
      - customerId
      - planId
      - productId
      - orderId
      - currentPeriodStart
      - currentPeriodEnd
      - nextChargeAt
      - trialEndsAt
      - cancelAtPeriodEnd
      - createdAt
      properties:
        id:
          type: string
        status:
          $ref: '#/components/schemas/PublicApiSubscriptionStatus'
        customerId:
          type: string
          nullable: true
          description: Null when the buyer could not be linked to a customer.
        planId:
          type: string
          nullable: true
          description: Null when the subscription is not on a catalogue plan.
        productId:
          type: string
          nullable: true
          description: Null when the subscription is not on a catalogue product.
        orderId:
          type: string
          nullable: true
          description: Order that started the subscription. Null for a plan checkout without an order.
        currentPeriodStart:
          type: string
          format: date-time
          nullable: true
          description: Start of the current billing period. Null on a subscription that has not renewed or changed since this field was added.
        currentPeriodEnd:
          type: string
          format: date-time
          nullable: true
          description: End of the current billing period. During a trial, the trial end.
        nextChargeAt:
          type: string
          format: date-time
          nullable: true
          description: 'When the next renewal charge is due. Null when no charge is scheduled: a pending cancellation, an ended subscription, or a one-time purchase.'
        trialEndsAt:
          type: string
          format: date-time
          nullable: true
          description: End of the free trial. Null when the subscription is not in a trial.
        cancelAtPeriodEnd:
          type: boolean
          description: True when the subscription ends at the end of the current period instead of renewing.
        createdAt:
          type: string
          format: date-time
      description: Subscription read. Every id is a Payments AI id.
  securitySchemes:
    UserOAuthCredentialAuth:
      type: http
      scheme: Bearer
      description: 'Signed-in user OAuth credential (`pai_mcp_*`) issued through the dashboard consent screen for this API: the authorization and token requests name the RFC 8707 resource `<API_URL>/v1/public-api` (ADR-0020). Credentials issued for the MCP server, or for no resource, are rejected with 401 `auth.invalid_token` and `WWW-Authenticate: Bearer resource_metadata="<API_URL>/.well-known/oauth-protected-resource/v1/public-api", error="invalid_token"`. Valid on the environment that issued it only. Each operation that accepts it names one required permission; a missing permission is 403 `auth.insufficient_scope` with `WWW-Authenticate: Bearer error="insufficient_scope", scope="<permission>"`. A merchant outside the user''s active memberships is 403 `merchant.access_forbidden`; a team role below the operation''s minimum is 403 `team.role_forbidden`.'
    MerchantApiKeyAuth:
      type: http
      scheme: Bearer
      description: 'Merchant API key from Developer Tools → API Keys. Example: `Authorization: Bearer pai_test_...`. Also accepted for any active sub-merchant this key''s own merchant created.'