Paid orders API

openapi: 3.2.0
info:
  title: Reference agents Orders API
  version: 1.0.0
servers:
- url: https://api.agentpaid.io/api/v1
  description: Production
tags:
- name: orders
paths:
  /orders:
    get:
      operationId: list
      summary: List orders
      tags:
      - orders
      parameters:
      - 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/Order'
    post:
      operationId: create
      summary: Create order
      tags:
      - orders
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreate'
  /orders/{orderId}:
    get:
      operationId: get
      summary: Get order by ID
      tags:
      - orders
      parameters:
      - name: orderId
        in: path
        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/Order'
    delete:
      operationId: delete
      summary: Delete order
      tags:
      - orders
      parameters:
      - name: orderId
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders_delete_Response_204'
  /orders/{orderId}/activate:
    post:
      operationId: activate
      summary: Activate order
      tags:
      - orders
      parameters:
      - name: orderId
        in: path
        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/Order'
  /orders/{orderId}/activate-and-pay:
    post:
      operationId: activate-and-pay
      summary: Activate order and process payment
      description: Activates the order and processes the initial payment using the provided Stripe confirmation token.
      tags:
      - orders
      parameters:
      - name: orderId
        in: path
        description: The order ID (can be internal ID or display ID)
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Order activated and payment processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Bad request - Invalid customer state or request body
          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: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                confirmationToken:
                  type: string
                  description: Stripe confirmation token for the payment method
                returnUrl:
                  type: string
                  description: URL to redirect to after payment processing
              required:
              - confirmationToken
              - returnUrl
  /orders/{orderId}/cancel:
    post:
      operationId: cancel-renewal
      summary: Cancel order renewal
      description: Schedules the cancellation of an order's renewal from a specified date. The order will remain active until the cancellation date.
      tags:
      - orders
      parameters:
      - name: orderId
        in: path
        description: The order ID (can be internal ID or display ID)
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Order renewal cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelRenewalResponse'
        '400':
          description: Bad request - Invalid order version or cancel from date
          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: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelRenewalRequest'
  /orders/{orderId}/schedule-plan-change:
    post:
      operationId: schedule-plan-change
      summary: Schedule a plan change with proration
      description: Schedules a plan upgrade or downgrade for an order with automatic proration calculation. Credits are applied for the unused portion of the current billing period.
      tags:
      - orders
      parameters:
      - name: orderId
        in: path
        description: The order ID (can be internal ID or display ID)
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Plan change scheduled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProrationUpgradeResponse'
        '400':
          description: Bad request - Invalid order version, effective date, or attributes
          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: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProrationUpgradeRequest'
  /orders/{orderId}/invoices:
    get:
      operationId: get-invoices
      summary: Get invoices for an order
      description: Retrieves all invoices associated with a specific order.
      tags:
      - orders
      parameters:
      - name: orderId
        in: path
        description: The order ID (can be internal ID or display ID)
        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:
                type: array
                items:
                  $ref: '#/components/schemas/Invoice'
        '403':
          description: Forbidden - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /orders/:
    get:
      operationId: list-orders
      summary: List orders
      description: Get a list of orders for the organization
      tags:
      - orders
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      - name: customerId
        in: query
        description: Filter by customer ID.
        required: false
        schema:
          type: string
      - name: externalCustomerId
        in: query
        description: Filter by customer external ID.
        required: false
        schema:
          type: string
      - name: externalId
        in: query
        description: Filter by the order's external ID (exact match).
        required: false
        schema:
          type: string
      - name: creationState
        in: query
        description: 'Filter by creation state: draft or active.'
        required: false
        schema:
          $ref: '#/components/schemas/OrdersGetParametersCreationState'
      - name: status
        in: query
        description: 'Filter by derived order status. draft: not yet activated. paused: billing is paused. ended: end date is in the past. active: activated, not paused, and not ended.'
        required: false
        schema:
          $ref: '#/components/schemas/OrdersGetParametersStatus'
      - name: startDateFrom
        in: query
        description: Only orders whose start date is on or after this date. Accepts an ISO 8601 date or date-time. Date-only values (e.g. 2026-06-30) are treated as UTC; date-times without an explicit timezone offset are ambiguous, so include one (e.g. 2026-06-30T00:00:00-05:00) when precision matters.
        required: false
        schema:
          type: string
      - name: startDateTo
        in: query
        description: Only orders whose start date is on or before this date. Accepts an ISO 8601 date or date-time. Date-only values (e.g. 2026-06-30) are treated as UTC; date-times without an explicit timezone offset are ambiguous, so include one (e.g. 2026-06-30T00:00:00-05:00) when precision matters.
        required: false
        schema:
          type: string
      - name: endDateFrom
        in: query
        description: Only orders whose end date is on or after this date. Orders without an end date are not matched. Accepts an ISO 8601 date or date-time. Date-only values (e.g. 2026-06-30) are treated as UTC; date-times without an explicit timezone offset are ambiguous, so include one (e.g. 2026-06-30T00:00:00-05:00) when precision matters.
        required: false
        schema:
          type: string
      - name: endDateTo
        in: query
        description: Only orders whose end date is on or before this date. Orders without an end date are not matched. Accepts an ISO 8601 date or date-time. Date-only values (e.g. 2026-06-30) are treated as UTC; date-times without an explicit timezone offset are ambiguous, so include one (e.g. 2026-06-30T00:00:00-05:00) when precision matters.
        required: false
        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/OrderListResponse'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: create-order
      summary: Create a new order
      description: Creates a new order for the organization
      tags:
      - orders
      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/Order_2'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '403'
          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/CreateOrderRequest'
  /orders/{id}:
    get:
      operationId: get-order-by-id
      summary: Get order
      description: Get an order by ID
      tags:
      - orders
      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/Order_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-order-by-id
      summary: Update order
      description: Update an order by ID
      tags:
      - orders
      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/Order_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/UpdateOrderRequest'
    delete:
      operationId: delete-order-by-id
      summary: Delete order
      description: Delete an order by ID
      tags:
      - orders
      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/EmptyResponse'
        '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'
  /orders/{id}/activate:
    post:
      operationId: activate-order-by-id
      summary: Activate order
      description: Activate a draft order by ID. Activation starts billing for the order using the same validation and side effects as the dashboard activation flow.
      tags:
      - orders
      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/Order_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'
  /orders/{id}/lines:
    get:
      operationId: get-order-lines
      summary: Get order lines
      description: Get the order lines for an order by ID
      tags:
      - orders
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      - 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/OrderLinesResponse'
        '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'
  /orders/{id}/seats:
    get:
      operationId: list-order-seats
      summary: List seats
      description: List seats for an order
      tags:
      - orders
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      - name: productExternalId
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/OrdersIdSeatsGetParametersStatus'
      - 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/OrderSeatListResponse'
        '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'
  /orders/{id}/seats/{seatId}:
    put:
      operationId: update-order-seat-assignment
      summary: Assign or unassign seat
      description: Assign or unassign a single seat on an order
      tags:
      - orders
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: seatId
        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/OrderSeat'
        '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'
        '409':
          description: '409'
          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/UpdateSeatAssignmentRequest'
  /orders/{id}/seat-assignments:
    post:
      operationId: batch-order-seat-assignments
      summary: Batch assign seats
      description: Assign or unassign seats in batch for an order
      tags:
      - orders
      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/BatchSeatAssignmentsResponse'
        '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'
        '409':
          description: '409'
          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/BatchSeatAssignmentsRequest'
components:
  schemas:
    Pagination:
      type: object
      properties:
        limit:
          type: integer
        offset:
          type: integer
        total:
          type: integer
        hasMore:
          type: boolean
      required:
      - limit
      - offset
      - total
      - hasMore
      title: Pagination
    CreateOrderLineAttributeRequestPricingCreditUnitBracketsItems:
      type: object
      properties:
        upTo:
          type:
          - integer
          - 'null'
        creditUnits:
          type: integer
      required:
      - upTo
      - creditUnits
      title: CreateOrderLineAttributeRequestPricingCreditUnitBracketsItems
    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
    CreateOrderLineAttributeRequestPricingBillingType:
      type: string
      enum:
      - advance
      - arrears
      title: CreateOrderLineAttributeRequestPricingBillingType
    OrderBillingFrequencyOverrideFrequency:
      type: string
      enum:
      - monthly
      - quarterly
      - semiAnnually
      - annual
      - custom
      title: OrderBillingFrequencyOverrideFrequency
    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
    CreateOrderLineAttributeRequest:
      type: object
      properties:
        name:
          type: string
        quantity:
          type: integer
        pricing:
          $ref: '#/components/schemas/CreateOrderLineAttributeRequestPricing'
      required:
      - name
      - pricing
      title: CreateOrderLineAttributeRequest
    OrderSeat:
      type: object
      properties:
        id:
          type: string
        orderId:
          type: string
        productExternalId:
          type:
          - string
          - 'null'
        status:
          $ref: '#/components/schemas/SeatAssignmentStatus'
        assignee:
          $ref: '#/components/schemas/SeatAssignee'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
      - id
      - orderId
      - productExternalId
      - status
      - assignee
      - createdAt
      - updatedAt
      title: OrderSeat
    CreateOrderLineAttributeRequestPricingPricePoints:
      type: object
      properties:
        currency:
          type: string
        unitPrice:
          type: number
          format: double
        minQuantity:
          type: number
          format: double
        includedQuantity:
          type: number
          format: double
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/CreateOrderLineAttributeRequestPricingPricePointsTiersItems'
      required:
      - unitPrice
      description: Single flat price point for this order attribute override. Do not send a currency-keyed map here.
      title: CreateOrderLineAttributeRequestPricingPricePoints
    OrderLineAttributeCreate:
      oneOf:
      - description: Any type
      - description: Any type
      title: OrderLineAttributeCreate
    CreateOrderLineAttributeRequestPricingPricingModel:
      type: string
      enum:
      - perUnit
      - volumePricing
      - graduatedPricing
      - prepaidCredits
      - bracketedPrepaidCredits
      - flat
      title: CreateOrderLineAttributeRequestPricingPricingModel
    ApiError:
      type: object
      properties:
        message:
          type: string
          description: A human-readable message providing more details about the error.
        code:
          type: string
        details:
          type: string
      description: An API error response from the Paid API
      title: ApiError
    PricePoint:
      type: object
      properties:
        currency:
          type: string
        unitPrice:
          type: number
          format: double
        minQuantity:
          type: number
          format: double
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/Tier'
      title: PricePoint
    BatchSeatAssignmentsRequest:
      type: object
      properties:
        assignments:
          type: array
          items:
            $ref: '#/components/schemas/BatchSeatAssignmentsRequestAssignmentsItems'
      required:
      - assignments
      title: BatchSeatAssignmentsRequest
    OrderCreate:
      type: object
      properties:
        customerId:
          type: string
        customerExternalId:
          type: string
        billingContactId:
          type: string
        name:
          type: string
        description:
          type: string
        startDate:
          type: string
        endDate:
          type: string
        currency:
          type: string
        planId:
          type: string
          format: uuid
          description: Optional plan ID to associate with thi

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