Paid plans API

openapi: 3.2.0
info:
  title: Reference agents Plans API
  version: 1.0.0
servers:
- url: https://api.agentpaid.io/api/v1
  description: Production
tags:
- name: plans
paths:
  /plans/current:
    get:
      operationId: get-current
      summary: Get customer's current plan
      description: Retrieves the currently active plan subscription for a customer by their external ID. Returns the plan details and subscription information.
      tags:
      - plans
      parameters:
      - name: customerExternalId
        in: query
        description: The external ID of the customer
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/plans_getCurrent_Response_200'
        '400':
          description: Bad request - Missing customerExternalId parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /plans/{planId}:
    get:
      operationId: get-by-id
      summary: Get plan by ID
      tags:
      - plans
      parameters:
      - name: planId
        in: path
        description: The ID of the plan
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan'
        '403':
          description: Forbidden - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Plan not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /plans/{planId}/usage:
    get:
      operationId: get-usage
      summary: Fetch usage summaries for a plan and customer
      tags:
      - plans
      parameters:
      - name: planId
        in: path
        description: The ID of the plan
        required: true
        schema:
          type: string
          format: uuid
      - name: externalId
        in: query
        description: The external ID of the customer
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of usage summaries to return (1-1000)
        required: false
        schema:
          type: integer
          default: 100
      - name: offset
        in: query
        description: Number of usage summaries to skip for pagination
        required: false
        schema:
          type: integer
          default: 0
      - name: startTime
        in: query
        description: Filter usage summaries starting from this time (ISO 8601 format). Returns summaries that overlap with the time range.
        required: false
        schema:
          type: string
          format: date-time
      - name: endTime
        in: query
        description: Filter usage summaries up to this time (ISO 8601 format). Returns summaries that overlap with the time range.
        required: false
        schema:
          type: string
          format: date-time
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageSummariesResponse'
        '400':
          description: Bad request - Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Plan or customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /plans/{planId}/subscribe:
    post:
      operationId: subscribe
      summary: Subscribe customer to plan
      description: Creates a new order for a customer subscribing to a plan. The order will be created with the plan's products and pricing attributes.
      tags:
      - plans
      parameters:
      - name: planId
        in: path
        description: The ID of the plan
        required: true
        schema:
          type: string
          format: uuid
      - name: customerExternalId
        in: query
        description: The external ID of the customer
        required: true
        schema:
          type: string
      - name: currency
        in: query
        description: The currency code for the order (e.g., "USD", "EUR")
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Customer subscribed to plan successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Bad request - Missing required parameters or invalid plan type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Plan or customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /plans/{planId}/unsubscribe:
    post:
      operationId: unsubscribe
      summary: Unsubscribe customer from plan
      description: Cancels the renewal of an active order for a customer's plan subscription. The order will remain active until the cancellation date.
      tags:
      - plans
      parameters:
      - name: planId
        in: path
        description: The ID of the plan
        required: true
        schema:
          type: string
          format: uuid
      - name: customerExternalId
        in: query
        description: The external ID of the customer
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Customer unsubscribed from plan successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelRenewalResponse'
        '400':
          description: Bad request - Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Plan, customer, or order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /plans/upgrade:
    post:
      operationId: upgrade
      summary: Upgrade customer to a new plan
      description: Upgrades a customer from one plan to another with automatic proration. Credits are applied for the unused portion of the current billing period, and the order is updated with the new plan's pricing.
      tags:
      - plans
      parameters:
      - name: customerExternalId
        in: query
        description: The external ID of the customer
        required: true
        schema:
          type: string
      - name: oldPlanId
        in: query
        description: The ID of the current plan
        required: true
        schema:
          type: string
          format: uuid
      - name: newPlanId
        in: query
        description: The ID of the plan to upgrade to
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Plan upgrade completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProrationUpgradeResponse'
        '400':
          description: Bad request - Missing required parameters, no matching attributes, or invalid plan configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Plan, customer, or order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /plans/planGroup/{planGroupId}:
    get:
      operationId: get-group-by-id
      summary: Get plan group by ID
      tags:
      - plans
      parameters:
      - name: planGroupId
        in: path
        description: The ID of the plan group
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanGroup'
        '403':
          description: Forbidden - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Plan group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /plans/planGroup/{planGroupId}/plans:
    get:
      operationId: get-group-plans
      summary: Get plans for a plan group
      description: Retrieves all plans in a plan group with their features (product-attribute pairs)
      tags:
      - plans
      parameters:
      - name: planGroupId
        in: path
        description: The ID of the plan group
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlanWithFeatures'
        '403':
          description: Forbidden - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Plan group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /plans/:
    get:
      operationId: list-plans
      summary: List plans
      description: Returns plans for your organization, including archived plans by default, optionally filtered to a product.
      tags:
      - plans
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      - name: productId
        in: query
        required: false
        schema:
          type: string
      - name: externalProductId
        in: query
        required: false
        schema:
          type: string
      - name: includeArchived
        in: query
        description: Whether to include archived plans in the response. Defaults to true.
        required: false
        schema:
          type: boolean
          default: true
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanListResponse'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: create-plan
      summary: Create a new plan
      description: Creates a new plan for a product.
      tags:
      - plans
      parameters:
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '201':
          description: '201'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan_2'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlanRequest'
  /plans/upgrade-path:
    put:
      operationId: update-plan-upgrade-path
      summary: Update plan upgrade path
      description: Updates upgrade path ordering for plans within a product, grouped by billing frequency.
      tags:
      - plans
      parameters:
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanUpgradePathResponse'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePlanUpgradePathRequest'
  /plans/{id}:
    get:
      operationId: get-plan-by-id
      summary: Get plan
      description: Get a plan by Paid plan ID.
      tags:
      - plans
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan_2'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: update-plan-by-id
      summary: Update plan
      description: Update a plan by Paid plan ID. If attributes are provided, they replace the plan's existing attributes. Set status to archive or restore the plan.
      tags:
      - plans
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan_2'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePlanRequest'
  /plans/external/{externalId}:
    get:
      operationId: get-plan-by-external-id
      summary: Get plan by external ID
      description: Get a plan by your external plan ID.
      tags:
      - plans
      parameters:
      - name: externalId
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan_2'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: update-plan-by-external-id
      summary: Update plan by external ID
      description: Update a plan by your external plan ID. If attributes are provided, they replace the plan's existing attributes. Set status to archive or restore the plan.
      tags:
      - plans
      parameters:
      - name: externalId
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan_2'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePlanRequest'
components:
  schemas:
    PlanUpgradePathGroup:
      type: object
      properties:
        frequency:
          type:
          - string
          - 'null'
        planIds:
          type: array
          items:
            type: string
      required:
      - frequency
      - planIds
      title: PlanUpgradePathGroup
    Pagination:
      type: object
      properties:
        limit:
          type: integer
        offset:
          type: integer
        total:
          type: integer
        hasMore:
          type: boolean
      required:
      - limit
      - offset
      - total
      - hasMore
      title: Pagination
    PlanType:
      type: string
      enum:
      - flat
      - usage
      - credit
      description: The type of plan (flat for fixed pricing, usage for usage-based, credit for prepaid credits)
      title: PlanType
    UpdatePlanUpgradePathRequest:
      type: object
      properties:
        productId:
          type: string
          description: Paid product ID, for example `prod_abc123`
        groups:
          type: array
          items:
            $ref: '#/components/schemas/PlanUpgradePathGroup'
      required:
      - productId
      - groups
      title: UpdatePlanUpgradePathRequest
    PlanCreditBenefitCreditGrantTiming:
      type: string
      enum:
      - on_payment
      - on_invoice_posted
      - on_order_activation
      title: PlanCreditBenefitCreditGrantTiming
    ProductSimplePricePointTiersItemsTierBillingType:
      type: string
      enum:
      - flat
      - perUnit
      title: ProductSimplePricePointTiersItemsTierBillingType
    PlanPricing:
      type: object
      properties:
        PricePoints:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PricePoint'
          description: Price points keyed by currency code (e.g., "USD", "EUR")
        billingFrequency:
          $ref: '#/components/schemas/PlanPricingBillingFrequency'
          description: The billing frequency for the plan
        billingFrequencyCustomMonths:
          type: number
          format: double
          description: Custom billing frequency in months (when billingFrequency is "custom")
      required:
      - PricePoints
      - billingFrequency
      description: The pricing configuration for a plan. Uses the same PricePoints structure as product pricing.
      title: PlanPricing
    ChargeType:
      type: string
      enum:
      - oneTime
      - recurring
      - usage
      - seatBased
      title: ChargeType
    Pricing:
      type: object
      properties:
        eventName:
          type: string
        taxable:
          type: boolean
        creditCost:
          type: number
          format: double
        chargeType:
          $ref: '#/components/schemas/ChargeType'
        pricingModel:
          $ref: '#/components/schemas/PricingModelType'
        billingFrequency:
          $ref: '#/components/schemas/BillingFrequency'
        pricePoints:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentPricePoint'
      required:
      - taxable
      - chargeType
      - pricingModel
      - billingFrequency
      - pricePoints
      title: Pricing
    Product:
      type: object
      properties:
        id:
          type: string
          format: uuid
        externalId:
          type:
          - string
          - 'null'
        displayId:
          type: string
          description: Human-readable display ID
        organizationId:
          type: string
          format: uuid
        name:
          type: string
        description:
          type:
          - string
          - 'null'
        type:
          $ref: '#/components/schemas/ProductType'
          description: The type of product
        active:
          type: boolean
        productCode:
          type:
          - string
          - 'null'
        ProductAttribute:
          type: array
          items:
            $ref: '#/components/schemas/AgentAttribute'
          description: Pricing attributes for this product
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
      - id
      - organizationId
      - name
      - type
      - active
      description: A product in the Paid system (previously called Agent)
      title: Product
    PlanPricingPricingType:
      type: string
      enum:
      - RecurringPerUnit
      - RecurringGraduated
      - RecurringVolume
      - RecurringPercentOfTotal
      - UsagePerUnit
      - UsageGraduated
      - UsageVolume
      - UsagePrepaidCredits
      - UsageBracketedPrepaidCredits
      - UsageCostPlus
      - OneTimePerUnit
      - SeatBasedPerUnit
      - SeatBasedGraduated
      - SeatBasedVolume
      - SeatBasedPrepaidCredits
      title: PlanPricingPricingType
    PlanPlanProductsItems:
      type: object
      properties:
        id:
          type: string
          format: uuid
        organizationId:
          type: string
          format: uuid
        planId:
          type: string
          format: uuid
        productId:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        product:
          $ref: '#/components/schemas/Product'
          description: The product associated with this plan product
        planProductAttribute:
          type: array
          items:
            $ref: '#/components/schemas/PlanPlanProductsItemsPlanProductAttributeItems'
          description: The product attributes with pricing for this plan
      title: PlanPlanProductsItems
    ProductPricingInputDiscriminatorMappingUsageBracketedPrepaidCreditsBillingType:
      type: string
      enum:
      - Advance
      - Arrears
      default: Arrears
      title: ProductPricingInputDiscriminatorMappingUsageBracketedPrepaidCreditsBillingType
    ProductPricingInputDiscriminatorMappingUsagePerUnitSignalType:
      type: string
      enum:
      - activity
      - outcome
      title: ProductPricingInputDiscriminatorMappingUsagePerUnitSignalType
    PlanCreditBenefitRolloverDurationUnit:
      type: string
      enum:
      - days
      - months
      title: PlanCreditBenefitRolloverDurationUnit
    ProductPricingInputDiscriminatorMappingUsageVolumeBillingFrequency:
      type: string
      enum:
      - Monthly
      - Quarterly
      - Semi-Annually
      - Annual
      - Custom
      title: ProductPricingInputDiscriminatorMappingUsageVolumeBillingFrequency
    AgentPricePoint:
      type: object
      properties:
        unitPrice:
          type: number
          format: double
        minQuantity:
          type: number
          format: double
        includedQuantity:
          type: number
          format: double
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/AgentPricePointTiers'
      title: AgentPricePoint
    ProductPricingInputDiscriminatorMappingRecurringVolumeBillingType:
      type: string
      enum:
      - Advance
      - Arrears
      default: Advance
      title: ProductPricingInputDiscriminatorMappingRecurringVolumeBillingType
    ProductPricingInputDiscriminatorMappingSeatBasedVolumeBillingFrequency:
      type: string
      enum:
      - Monthly
      - Quarterly
      - Semi-Annually
      - Annual
      - Custom
      title: ProductPricingInputDiscriminatorMappingSeatBasedVolumeBillingFrequency
    UsagePaginationMeta:
      type: object
      properties:
        limit:
          type: integer
          description: The requested limit
        offset:
          type: integer
          description: The requested offset
        total:
          type: integer
          description: Total number of usage summaries available
        hasMore:
          type: boolean
          description: Whether there are more results available
      required:
      - limit
      - offset
      - total
      - hasMore
      description: Pagination metadata for usage summaries
      title: UsagePaginationMeta
    PlanGroup:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the plan group
        organizationId:
          type: string
          format: uuid
          description: The organization ID that owns this plan group
        name:
          type: string
          description: The name of the plan group
        description:
          type:
          - string
          - 'null'
          description: The description of the plan group
        createdAt:
          type: string
          format: date-time
          description: When the plan group was created
        updatedAt:
          type: string
          format: date-time
          description: When the plan group was last updated
        plans:
          type: array
          items:
            $ref: '#/components/schemas/Plan'
          description: The plans included in this plan group
      required:
      - id
      - organizationId
      - name
      - createdAt
      - updatedAt
      description: A plan group containing multiple plans
      title: PlanGroup
    ProductType:
      type: string
      enum:
      - agent
      - product
      - prepaidCreditBundle
      description: The type of product
      title: ProductType
    PlanListResponse:
      type: obj

# --- truncated at 32 KB (89 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paid/refs/heads/main/openapi/paid-plans-api-openapi.yml