payments-ai Products API

openapi: 3.2.0
info:
  title: Payments AI MoR Merchant Public Products 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: Products
paths:
  /v1/public-api/merchants/{merchantId}/products:
    get:
      operationId: PublicApiProducts_list
      description: 'Auth: Merchant API key, or user OAuth credential with `product:read` · tenant `{merchantId}` · any team member · 401 `auth.invalid_token` · 403 `auth.insufficient_scope`, `merchant.access_forbidden`.'
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: q
        in: query
        required: false
        schema:
          type: string
        explode: false
      - name: status
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ProductStatus'
        explode: false
      - name: type
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/PlanType'
        explode: false
      - name: dateRangeStart
        in: query
        required: false
        schema:
          type: string
          format: date-time
        explode: false
      - name: dateRangeEnd
        in: query
        required: false
        schema:
          type: string
          format: date-time
        explode: false
      - name: page
        in: query
        required: false
        schema:
          type: integer
          format: int32
        explode: false
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          format: int32
        explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiProductListResponse'
      tags:
      - Products
      security:
      - MerchantApiKeyAuth: []
      - UserOAuthCredentialAuth: []
      summary: List products
    post:
      operationId: PublicApiProducts_create
      description: 'Auth: Merchant API key, or user OAuth credential with `product:create` · tenant `{merchantId}` · Owner, Admin, or Editor (user credential) · 401 `auth.invalid_token` · 403 `auth.insufficient_scope`, `merchant.access_forbidden`, `team.role_forbidden`. Send `Idempotency-Key` to make retries safe: the same key with the same body always returns the original product id, with no expiry once the product exists; the same key with a different body returns 409.'
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProductResponse'
      tags:
      - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicApiCreateProduct'
      security:
      - MerchantApiKeyAuth: []
      - UserOAuthCredentialAuth: []
      summary: Create product
  /v1/public-api/merchants/{merchantId}/products/{id}:
    get:
      operationId: PublicApiProducts_getById
      description: 'Auth: Merchant API key, or user OAuth credential with `product:read` · tenant `{merchantId}` · any team member · 401 `auth.invalid_token` · 403 `auth.insufficient_scope`, `merchant.access_forbidden`.'
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiProduct'
      tags:
      - Products
      security:
      - MerchantApiKeyAuth: []
      - UserOAuthCredentialAuth: []
      summary: Get product
    patch:
      operationId: PublicApiProducts_update
      description: 'Partial update; omitted fields keep their stored value. Auth: Merchant API key, or user OAuth credential with `product:create` · tenant `{merchantId}` · Owner, Admin, or Editor (user credential) · 401 `auth.invalid_token` · 403 `auth.insufficient_scope`, `merchant.access_forbidden`, `team.role_forbidden`.'
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiProduct'
      tags:
      - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicApiUpdateProductRequest'
      security:
      - MerchantApiKeyAuth: []
      - UserOAuthCredentialAuth: []
      summary: Update product
  /v1/public-api/merchants/{merchantId}/products/{id}/image/confirm:
    post:
      operationId: PublicApiProducts_confirmImage
      description: 'Step 2 of 2: confirm the uploaded object and link it to the product. The backend never fetches a client-supplied URL. Auth: Merchant API key, or user OAuth credential with `product:create` · tenant `{merchantId}` · Owner, Admin, or Editor (user credential) · 401 `auth.invalid_token` · 403 `auth.insufficient_scope`, `merchant.access_forbidden`, `team.role_forbidden`.'
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiConfirmProductImageResponse'
      tags:
      - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicApiConfirmProductImageRequest'
      security:
      - MerchantApiKeyAuth: []
      - UserOAuthCredentialAuth: []
      summary: Confirm image
  /v1/public-api/merchants/{merchantId}/products/{id}/image/upload-url:
    post:
      operationId: PublicApiProducts_createImageUploadUrl
      description: 'Step 1 of 2: mint an upload policy for the product image. Auth: Merchant API key, or user OAuth credential with `product:create` · tenant `{merchantId}` · Owner, Admin, or Editor (user credential) · 401 `auth.invalid_token` · 403 `auth.insufficient_scope`, `merchant.access_forbidden`, `team.role_forbidden`.'
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiProductImageUploadUrlResponse'
      tags:
      - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicApiProductImageUploadUrlRequest'
      security:
      - MerchantApiKeyAuth: []
      - UserOAuthCredentialAuth: []
      summary: Create image upload url
  /v1/public-api/merchants/{merchantId}/products/{id}/plans:
    get:
      operationId: PublicApiProducts_listPlans
      description: 'Auth: Merchant API key, or user OAuth credential with `product:read` · tenant `{merchantId}` · any team member · 401 `auth.invalid_token` · 403 `auth.insufficient_scope`, `merchant.access_forbidden`.'
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicApiPlan'
      tags:
      - Products
      security:
      - MerchantApiKeyAuth: []
      - UserOAuthCredentialAuth: []
      summary: List plans
    post:
      operationId: PublicApiProducts_createPlan
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiPlan'
      tags:
      - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlan'
      summary: Create plan
  /v1/public-api/merchants/{merchantId}/products/{id}/plans/{planId}:
    patch:
      operationId: PublicApiProducts_updatePlan
      description: 'Partial update of one plan; omitted fields keep their stored value. Auth: Merchant API key, or user OAuth credential with `product:create` · tenant `{merchantId}` · Owner, Admin, or Editor (user credential) · 401 `auth.invalid_token` · 403 `auth.insufficient_scope`, `merchant.access_forbidden`, `team.role_forbidden`.'
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: planId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiPlan'
      tags:
      - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicApiUpdatePlanRequest'
      security:
      - MerchantApiKeyAuth: []
      - UserOAuthCredentialAuth: []
      summary: Update plan
components:
  schemas:
    PublicApiUpdateProductRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 30
        description:
          type: string
          maxLength: 80
        status:
          type: string
          enum:
          - active
          - draft
          description: Only `active` and `draft` can be set here. Moving an active product with active subscriptions out of `active` returns 409.
        productTaxCodeId:
          type: string
          nullable: true
          description: Whop product tax code id for catalog sync; `null` clears it.
    ProductRevenueSummary:
      type: object
      required:
      - totalRevenue
      - currency
      - totalSalesCount
      properties:
        totalRevenue:
          $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
        currency:
          $ref: '#/components/schemas/SharedTypes.CurrencyCode'
        totalSalesCount:
          type: integer
          format: int32
    ProductListPricing:
      type: object
      required:
      - minPrice
      - maxPrice
      - currency
      - billingLabel
      - items
      properties:
        minPrice:
          $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
        maxPrice:
          $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
        currency:
          $ref: '#/components/schemas/SharedTypes.CurrencyCode'
        billingLabel:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProductListPricingItem'
    PublicApiProductImageUploadUrlResponse:
      type: object
      required:
      - url
      - fields
      - key
      - expiresIn
      properties:
        url:
          type: string
          description: S3 POST endpoint for the multipart/form-data upload.
        fields:
          type: object
          additionalProperties:
            type: string
          description: Form fields to include in the multipart body; the `file` field goes last.
        key:
          type: string
          description: Storage key to echo back to the confirm step. Bound to the merchant.
        expiresIn:
          type: integer
          format: int32
          description: Seconds until the upload policy expires.
    CreateBillingPeriod:
      type: string
      enum:
      - week
      - month
      - year
      description: Billing periods allowed when creating a new plan (daily is excluded for new plans).
    PublicApiProduct:
      type: object
      required:
      - id
      - merchantId
      - name
      - status
      - revenue
      - discountCodes
      - plans
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
        merchantId:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/ProductStatus'
        revenue:
          type: number
          format: decimal
        discountCodes:
          type: array
          items:
            type: string
          description: 'Deprecated: legacy discount codes on the product. New promos are first-class DiscountCode entities. Retained for backward compatibility until migration (PAIM-285).'
        plans:
          type: array
          items:
            $ref: '#/components/schemas/PublicApiPlanVariant'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        deletedAt:
          type: string
          format: date-time
          nullable: true
        imageUrl:
          type: string
          nullable: true
          description: Presigned URL resolved on the read side from the stored S3 image key.
        activeSubscriptionCount:
          type: integer
          format: int32
          description: Active subscriptions billed against this product
        totalSalesCount:
          type: integer
          format: int32
          description: Lifetime sales count for delete eligibility
        canPermanentlyDelete:
          type: boolean
          description: True when draft with zero sales and zero active subscriptions
        productTaxCodeId:
          type: string
          nullable: true
    PublicApiProductImageUploadUrlRequest:
      type: object
      required:
      - fileName
      - mimeType
      properties:
        fileName:
          type: string
          minLength: 1
          maxLength: 255
        mimeType:
          type: string
          enum:
          - image/png
          - image/jpeg
          - image/jpg
          - image/webp
      description: Request a short-lived presigned S3 POST policy for a product image. Upload size limit is 5 MB.
    PublicApiProductListResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PublicApiProductListItem'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    ProductListPricingItem:
      type: object
      required:
      - planId
      - name
      - amount
      - currency
      - type
      - checkoutUrl
      - isPrimary
      properties:
        planId:
          type: string
        name:
          type: string
          description: Merchant-facing display name of the plan variant.
        amount:
          $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
        currency:
          $ref: '#/components/schemas/SharedTypes.CurrencyCode'
        type:
          $ref: '#/components/schemas/PlanType'
        billingPeriod:
          allOf:
          - $ref: '#/components/schemas/BillingPeriod'
          description: Billing cadence. Present only for recurring plans; omitted for one-time and free-access.
        lengthOfBillingPeriod:
          type: integer
          format: int32
          description: Multiplier for the billing period. Present only for recurring plans; omitted for one-time and free-access.
        freeTrial:
          type: integer
          format: int32
          description: Remaining trial days when a trial is active. Omitted otherwise.
        checkoutUrl:
          type: string
        isPrimary:
          type: boolean
          description: True for the single plan the product-level checkoutUrl points to; false for all others.
    PublicApiConfirmProductImageRequest:
      type: object
      required:
      - key
      properties:
        key:
          type: string
          description: Exact `key` returned by the upload-url step.
    PublicApiProductListItem:
      type: object
      required:
      - id
      - name
      - status
      - variantCount
      - types
      - pricing
      - revenueSummary
      - checkoutUrl
      - createdAt
      properties:
        id:
          type: string
        name:
          type: string
        status:
          $ref: '#/components/schemas/ProductStatus'
        variantCount:
          type: integer
          format: int32
        types:
          type: array
          items:
            $ref: '#/components/schemas/PlanType'
        pricing:
          $ref: '#/components/schemas/ProductListPricing'
        revenueSummary:
          $ref: '#/components/schemas/ProductRevenueSummary'
        checkoutUrl:
          type: string
        createdAt:
          type: string
          format: date-time
        activeSubscriptionCount:
          type: integer
          format: int32
          description: Active subscriptions billed against this product; used for archive warning and delete gating
        canPermanentlyDelete:
          type: boolean
          description: True when the product is a draft with zero sales and zero active subscriptions
    CreatePlan:
      type: object
      required:
      - name
      - currency
      - amount
      - type
      - billingPeriod
      - periodLength
      properties:
        name:
          type: string
          maxLength: 30
        description:
          type: string
          maxLength: 80
        richDescription:
          type: string
          maxLength: 65535
        currency:
          $ref: '#/components/schemas/SharedTypes.CurrencyCode'
        amount:
          allOf:
          - $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
          description: Strictly flat pricing amount
        type:
          $ref: '#/components/schemas/PlanType'
        billingPeriod:
          $ref: '#/components/schemas/CreateBillingPeriod'
        periodLength:
          type: integer
          format: int32
          minimum: 1
        freeTrial:
          type: integer
          format: int32
          minimum: 0
        taxBehavior:
          type: string
          enum:
          - exclusive
          - inclusive
          description: Optional per-plan tax behaviour override. When omitted, the plan inherits the merchant default.
    PublicApiUpdatePlanRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 30
        description:
          type: string
          maxLength: 80
        type:
          allOf:
          - $ref: '#/components/schemas/PlanType'
          description: Immutable after creation; a value different from the plan's current type returns 409.
        billingPeriod:
          $ref: '#/components/schemas/BillingPeriod'
        lengthOfBillingPeriod:
          type: integer
          format: int32
          minimum: 1
        amount:
          allOf:
          - $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
          description: Must be zero for free-access plans. Changing amount or currency on a plan with active subscriptions returns 409.
        currency:
          $ref: '#/components/schemas/SharedTypes.CurrencyCode'
        freeTrial:
          type: integer
          format: int32
          minimum: 0
        taxBehavior:
          type: string
          enum:
          - exclusive
          - inclusive
          nullable: true
          description: '`null` clears the override so the plan inherits the merchant default.'
    PublicApiPlan:
      type: object
      required:
      - id
      - productId
      - name
      - type
      - billingPeriod
      - lengthOfBillingPeriod
      - amount
      - initialPrice
      - currency
      - freeTrial
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
        productId:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        type:
          type: string
        billingPeriod:
          type: string
        lengthOfBillingPeriod:
          type: integer
          format: int32
        amount:
          $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
        initialPrice:
          allOf:
          - $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
          description: Amount charged at checkout today. Zero for recurring plans with a free trial; otherwise matches amount.
        currency:
          type: string
        freeTrial:
          type: integer
          format: int32
        taxBehavior:
          type: string
          enum:
          - exclusive
          - inclusive
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    BillingPeriod:
      type: string
      enum:
      - day
      - week
      - month
      - year
    PublicApiPlanVariant:
      type: object
      required:
      - id
      - productId
      - name
      - type
      - billingPeriod
      - lengthOfBillingPeriod
      - amount
      - initialPrice
      - currency
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
        productId:
          type: string
        name:
          type: string
          maxLength: 30
          description: Merchant-facing display name for the variant (e.g. Pro, Monthly).
        description:
          type: string
          nullable: true
          maxLength: 80
        type:
          $ref: '#/components/schemas/PlanType'
        billingPeriod:
          $ref: '#/components/schemas/BillingPeriod'
        lengthOfBillingPeriod:
          type: integer
          format: int32
        amount:
          allOf:
          - $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
          description: Strictly flat pricing amount
        initialPrice:
          allOf:
          - $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
          description: Amount charged at checkout today. Zero for recurring plans with a free trial; otherwise matches amount.
        currency:
          $ref: '#/components/schemas/SharedTypes.CurrencyCode'
        freeTrial:
          type: integer
          format: int32
        taxBehavior:
          type: string
          enum:
          - exclusive
          - inclusive
          nullable: true
          description: Per-plan override when set; otherwise inherits merchant default.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ProductStatus:
      type: string
      enum:
      - active
      - draft
      - archived
    PublicApiCreateProduct:
      type: object
      required:
      - name
      - plans
      properties:
        name:
          type: string
          maxLength: 30
        description:
          type: string
          maxLength: 80
        status:
          $ref: '#/components/schemas/ProductStatus'
        discountCode:
          type: string
          description: 'Deprecated: legacy discount codes on the product. New promos are first-class DiscountCode entities.'
        plans:
          type: array
          items:
            $ref: '#/components/schemas/CreatePlan'
        imagePath:
          type: string
          maxLength: 255
        productTaxCodeId:
          type: string
          description: Optional Whop product tax code id for catalog sync.
    CreateProductResponse:
      type: object
      required:
      - id
      properties:
        id:
          type: string
    SharedTypes.MoneyAmountValue:
      type: number
      format: decimal
      description: Decimal money amount for financial values.
    SharedTypes.CurrencyCode:
      type: string
      pattern: ^[a-z]{3}$
      description: ISO 4217 currency code. Always lowercase (e.g. 'usd', 'eur').
    PlanType:
      type: string
      enum:
      - free-access
      - one-time
      - recurring
    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
    PublicApiConfirmProductImageResponse:
      type: object
      required:
      - imageUrl
      properties:
        imageUrl:
          type: string
          description: Presigned GET URL for the stored image.
  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.'