Paid orders API

openapi: 3.1.0
info:
  title: API 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:
    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
    PricingModelType:
      type: string
      enum:
      - PerUnit
      - VolumePricing
      - GraduatedPricing
      - PrepaidCredits
      title: PricingModelType
    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
    CreateOrderLineAttributeRequestPricingBillingFrequency:
      type: string
      enum:
      - monthly
      - quarterly
      - semiAnnually
      - annual
      - custom
      title: CreateOrderLineAttributeRequestPricingBillingFrequency
    OrderCreationState:
      type: string
      enum:
      - draft
      - active
      title: OrderCreationState
    Invoice:
      type: object
      properties:
        id:
          type: string
          format: uuid
        displayId:
          type: string
          description: Human-readable invoice number
        organizationId:
          type: string
          format: uuid
        customerId:
          type: string
          format: uuid
        orderId:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/InvoiceStatus'
        currency:
          type: string
        subtotal:
          type: number
          format: double
          description: Total before tax (in smallest currency unit)
        tax:
          type: number
          format: double
          description: Tax amount (in smallest currency unit)
        total:
          type: number
          format: double
          description: Total amount including tax (in smallest currency unit)
        amountPaid:
          type: number
          format: double
          description: Amount already paid (in smallest currency unit)
        amountDue:
          type: number
          format: double
          description: Amount still due (in smallest currency unit)
        dueDate:
          type: string
          format: date-time
        paidAt:
          type:
          - string
          - 'null'
          format: date-time
        voidedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        customer:
          $ref: '#/components/schemas/Customer'
      description: An invoice for an order
      title: Invoice
    CreateOrderLineAttributeRequestPricingCreditBenefitsItemsRecipient:
      type: string
      enum:
      - organization
      - seat
      title: CreateOrderLineAttributeRequestPricingCreditBenefitsItemsRecipient
    EmptyResponse:
      type: object
      properties: {}
      title: EmptyResponse
    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
    SeatAssignmentStatus:
      type: string
      enum:
      - assigned
      - unassigned
      title: SeatAssignmentStatus
    Pagination:
      type: object
      properties:
        limit:
          type: integer
        offset:
          type: integer
        total:
          type: integer
        hasMore:
          type: boolean
      required:
      - limit
      - offset
      - total
      - hasMore
      title: Pagination
    CreateOrderLineAttributeRequestPricingPricingInput:
      type: object
      properties:
        kind:
          $ref: '#/components/schemas/CreateOrderLineAttributeRequestPricingPricingInputKind'
      required:
      - kind
      title: CreateOrderLineAttributeRequestPricingPricingInput
    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 this order
        orderLines:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineCreate'
      r

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