Paid plans API

openapi: 3.1.0
info:
  title: API 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:
    ProductPricingInputDiscriminatorMappingSeatBasedGraduatedBillingType:
      type: string
      enum:
      - Advance
      - Arrears
      default: Advance
      title: ProductPricingInputDiscriminatorMappingSeatBasedGraduatedBillingType
    ProductPricingInputDiscriminatorMappingUsageVolumeSignalType:
      type: string
      enum:
      - activity
      - outcome
      title: ProductPricingInputDiscriminatorMappingUsageVolumeSignalType
    ProductPricingInputDiscriminatorMappingSeatBasedVolumeBillingFrequency:
      type: string
      enum:
      - Monthly
      - Quarterly
      - Semi-Annually
      - Annual
      - Custom
      title: ProductPricingInputDiscriminatorMappingSeatBasedVolumeBillingFrequency
    PricingModelType:
      type: string
      enum:
      - PerUnit
      - VolumePricing
      - GraduatedPricing
      - PrepaidCredits
      title: PricingModelType
    Agent:
      type: object
      properties:
        id:
          type: string
        externalId:
          type: string
        organizationId:
          type: string
        name:
          type: string
        description:
          type: string
        active:
          type: boolean
        agentCode:
          type: string
        agentAttributes:
          type: array
          items:
            $ref: '#/components/schemas/AgentAttribute'
      required:
      - id
      - organizationId
      - name
      - active
      title: Agent
    Customer:
      type: object
      properties:
        id:
          type: string
        organizationId:
          type: string
        name:
          type: string
        externalId:
          type: string
        phone:
          type: string
        employeeCount:
          type: number
          format: double
        annualRevenue:
          type: number
          format: double
        taxExemptStatus:
          $ref: '#/components/schemas/TaxExemptStatus'
        creationSource:
          $ref: '#/components/schemas/CreationSource'
        creationState:
          $ref: '#/components/schemas/CreationState'
        website:
          type: string
        billingAddress:
          $ref: '#/components/schemas/Address'
        metadata:
          $ref: '#/components/schemas/CustomerMetadata'
          description: Flexible JSON field for storing custom metadata about the customer
      required:
      - id
      - organizationId
      - name
      title: Customer
    ProductPricingInputDiscriminatorMappingUsageBracketedPrepaidCreditsBillingFrequency:
      type: string
      enum:
      - Monthly
      - Quarterly
      - Semi-Annually
      - Annual
      - Custom
      title: ProductPricingInputDiscriminatorMappingUsageBracketedPrepaidCreditsBillingFrequency
    ProductPricingInputDiscriminatorMappingUsageVolumeBillingType:
      type: string
      enum:
      - Advance
      - Arrears
      default: Arrears
      title: ProductPricingInputDiscriminatorMappingUsageVolumeBillingType
    UsageSummaryOrder:
      type: object
      properties:
        id:
          type: string
          format: uuid
        displayId:
          type:
          - string
          - 'null'
      description: Associated order information
      title: UsageSummaryOrder
    PlanWithFeatures:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the plan
        name:
          type: string
          description: The name of the plan
        description:
          type:
          - string
          - 'null'
          description: The description of the plan
        type:
          $ref: '#/components/schemas/PlanWithFeaturesType'
          description: The type of plan (flat for fixed pricing, usage for usage-based, credit for prepaid credits)
        pricing:
          $ref: '#/components/schemas/PlanPricing'
        createdAt:
          type: string
          format: date-time
          description: When the plan was created
        updatedAt:
          type: string
          format: date-time
          description: When the plan was last updated
        nextPlanId:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the next plan in the sequence
        prevPlanId:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the previous plan in the sequence
        features:
          type: array
          items:
            $ref: '#/components/schemas/PlanWithFeaturesFeaturesItems'
          description: The features (product-attribute pairs) included in this plan
      required:
      - id
      - name
      - type
      - pricing
      - createdAt
      - updatedAt
      - features
      description: A plan with its features (product-attribute pairs) for display
      title: PlanWithFeatures
    ProductPricingInputDiscriminatorMappingUsageCostPlusBillingType:
      type: string
      enum:
      - Advance
      - Arrears
      default: Arrears
      title: ProductPricingInputDiscriminatorMappingUsageCostPlusBillingType
    plans_getCurrent_Response_200:
      type: object
      properties:
        plan:
          oneOf:
          - $ref: '#/components/schemas/PlansCurrentGetResponsesContentApplicationJsonSchemaPlan'
          - type: 'null'
          description: The plan details, or null if the customer has no active plan
        subscription:
          oneOf:
          - $ref: '#/components/schemas/PlansCurrentGetResponsesContentApplicationJsonSchemaSubscription'
          - type: 'null'
          description: The subscription details, or null if the customer has no active plan
      required:
      - plan
      - subscription
      title: plans_getCurrent_Response_200
    ProductPricingInputDiscriminatorMappingUsagePerUnitSignalType:
      type: string
      enum:
      - activity
      - outcome
      title: ProductPricingInputDiscriminatorMappingUsagePerUnitSignalType
    Plan_2:
      type: object
      properties:
        id:
          type: string
        productId:
          type: string
        name:
          type:
          - string
          - 'null'
        externalId:
          type:
          - string
          - 'null'
        supportedCurrencies:
          type: array
          items:
            type: string
        isDefault:
          type: boolean
        status:
          $ref: '#/components/schemas/PlanStatus'
        upgradePathOrder:
          type:
          - number
          - 'null'
          format: double
        archivedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/PlanAttribute'
      required:
      - id
      - productId
      - name
      - externalId
      - supportedCurrencies
      - isDefault
      - status
      - upgradePathOrder
      - archivedAt
      - createdAt
      - updatedAt
      - attributes
      title: Plan
    PlanCreditBenefitRecipient:
      type: string
      enum:
      - organization
      - seat
      title: PlanCreditBenefitRecipient
    ProductType:
      type: string
      enum:
      - agent
      - product
      - prepaidCreditBundle
      description: The type of product
      title: ProductType
    PlanListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Plan_2'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - data
      - pagination
      title: PlanListResponse
    OrderLineAttributePricing:
      type: object
      properties:
        eventName:
          type: string
        chargeType:
          $ref: '#/components/schemas/ChargeType'
        pricePoint:
          $ref: '#/components/schemas/PricePoint'
        pricingModel:
          $ref: '#/components/schemas/PricingModelType'
        billingFrequency:
          $ref: '#/components/schemas/BillingFrequency'
      title: OrderLineAttributePricing
    ProductPricingInput:
      oneOf:
      - type: object
        properties:
          pricingType:
            type: string
            enum:
            - RecurringPerUnit
            description: 'Discriminator value: RecurringPerUnit'
          billingFrequency:
            $ref: '#/components/schemas/ProductPricingInputDiscriminatorMappingRecurringPerUnitBillingFrequency'
          billingFrequencyCustomMonths:
            type: integer
          billingType:
            $ref: '#/components/schemas/ProductPricingInputDiscriminatorMappingRecurringPerUnitBillingType'
          pricePoints:
            type: array
            items:
              $ref: '#/components/schemas/ProductSimplePricePoint'
        required:
        - pricingType
        - billingFrequency
        - pricePoints
        description: RecurringPerUnit variant
      - type: object
        properties:
          pricingType:
            type: string
            enum:
            - RecurringGraduated
            description: 'Discriminator value: RecurringGraduated'
          billingFrequency:
            $ref: '#/components/schemas/ProductPricingInputDiscriminatorMappingRecurringGraduatedBillingFrequency'
          billingFrequencyCustomMonths:
            type: integer
          billingType:
            $ref: '#/components/schemas/ProductPricingInputDiscriminatorMappingRecurringGraduatedBillingType'

# --- 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