openapi: 3.0.3
info:
  title: RecVue API
  description: >-
    RecVue is an enterprise revenue management platform (RevOS) covering
    order-to-cash, billing, usage-based monetization, pricing, and ASC 606 /
    IFRS 15 revenue recognition. This OpenAPI is derived from RecVue's public
    developer reference at https://developer.recvue.com. The base URLs, the
    OAuth2 client-credentials authentication, and the paths for representative
    operations (for example GET /orders) are confirmed from that public
    reference; the full request/response schemas are honestly modeled from the
    documented resource operations rather than reproduced field-for-field, and
    RecVue tenants (production and sandbox) are provisioned through an
    enterprise sales process. Endpoints marked with `x-endpointsModeled: true`
    reflect documented operations whose exact path or payload was not verified
    verbatim. Treat this as a navigational model, not a generated client
    contract; consult developer.recvue.com/reference for authoritative detail.
  version: '2.0'
  contact:
    name: RecVue
    url: https://www.recvue.com/
servers:
  - url: https://api.recvue.com/api/v2.0
    description: Production
  - url: https://sandbox-api.recvue.com/api/v2.0
    description: Sandbox
security:
  - oauth2ClientCredentials: []
tags:
  - name: Authentication
    description: OAuth2 client-credentials token issuance.
  - name: Orders
    description: Order and order-line lifecycle (order-to-cash).
  - name: Billing
    description: Bill runs and invoice generation.
  - name: Billing Schedules
    description: Dated billing schedule records.
  - name: Pricing
    description: Price lists, tier pricing, and pricing rules.
  - name: Usage
    description: Usage/delivery ingestion for consumption billing.
  - name: Customers
    description: Customer accounts, sites, and contacts.
  - name: Invoices
    description: Invoices and adjustments (AR integration).
  - name: Revenue Recognition
    description: ASC 606 / IFRS 15 revenue-contract configuration.
  - name: Programs
    description: Asynchronous concurrent programs (bill runs, revenue, exports).
paths:
  /api/scim/oauth/token:
    post:
      operationId: issueAccessToken
      tags:
        - Authentication
      summary: Issue OAuth2 access token
      description: >-
        Issues an access token using the client_credentials grant. Authenticate
        with a Basic auth header or by passing client_id/client_secret as form
        parameters. Content-Type is application/x-www-form-urlencoded.
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
              properties:
                grant_type:
                  type: string
                  enum: [client_credentials]
                client_id:
                  type: string
                client_secret:
                  type: string
                scope:
                  type: string
      responses:
        '200':
          description: An access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessToken'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /orders:
    get:
      operationId: getOrders
      tags:
        - Orders
      summary: Get orders
      description: >-
        Retrieves a paginated list of orders with comprehensive filtering
        options.
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A paginated list of orders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createOrder
      tags:
        - Orders
      summary: Create order
      description: >-
        Creates an order. Supports hundreds of standard and custom fields
        including revenue settings and billing associations.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: The created order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /orders/{orderId}:
    parameters:
      - name: orderId
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getOrderById
      tags:
        - Orders
      summary: Get order by ID
      x-endpointsModeled: true
      responses:
        '200':
          description: The order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: updateOrder
      tags:
        - Orders
      summary: Update order
      x-endpointsModeled: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: The updated order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
    delete:
      operationId: deleteOrder
      tags:
        - Orders
      summary: Delete order
      description: Irreversible operation removing an order and its lines.
      x-endpointsModeled: true
      responses:
        '204':
          description: Deleted.
  /orders/{orderId}/activate:
    post:
      operationId: activateOrder
      tags:
        - Orders
      summary: Activate order
      description: Enables billing schedule generation for the order.
      x-endpointsModeled: true
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The activated order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
  /orders/{orderId}/terminate:
    post:
      operationId: terminateOrder
      tags:
        - Orders
      summary: Terminate order
      description: Full or partial cancellation with credit options.
      x-endpointsModeled: true
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The terminated order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
  /billruns:
    get:
      operationId: getBillRuns
      tags:
        - Billing
      summary: Get bill runs
      description: Retrieves bill runs with advanced filtering by name, date, and status.
      x-endpointsModeled: true
      responses:
        '200':
          description: A list of bill runs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BillRun'
    post:
      operationId: createBillRun
      tags:
        - Billing
      summary: Create bill run
      description: >-
        Generates invoices. Status flows CREATED to PROCESSING to COMPLETED.
      x-endpointsModeled: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillRun'
      responses:
        '200':
          description: The created bill run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillRun'
  /billingschedules:
    get:
      operationId: getBillingSchedules
      tags:
        - Billing Schedules
      summary: Get billing schedules
      description: Paginated retrieval of billing schedules with filters.
      x-endpointsModeled: true
      responses:
        '200':
          description: A list of billing schedules.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BillingSchedule'
    post:
      operationId: createBillingSchedule
      tags:
        - Billing Schedules
      summary: Create billing schedule
      description: Creates manual schedules for one-time or milestone billing.
      x-endpointsModeled: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingSchedule'
      responses:
        '200':
          description: The created billing schedule.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingSchedule'
  /pricelists:
    get:
      operationId: getPriceLists
      tags:
        - Pricing
      summary: Get price lists
      description: Paginated retrieval of price lists with filtering.
      x-endpointsModeled: true
      responses:
        '200':
          description: A list of price lists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PriceList'
  /usage/batches:
    post:
      operationId: loadUsageBatch
      tags:
        - Usage
      summary: Load usage records into batch
      description: >-
        Loads usage records as a JSON payload routed to the Usage Hub for
        consumption-based billing.
      x-endpointsModeled: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsageBatch'
      responses:
        '200':
          description: The accepted usage batch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageBatch'
  /deliveries:
    get:
      operationId: getDeliveries
      tags:
        - Usage
      summary: List usages/deliveries
      description: Paginated ORDER_DELIVERIES records.
      x-endpointsModeled: true
      responses:
        '200':
          description: A list of deliveries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Delivery'
  /customers:
    get:
      operationId: getCustomerAccounts
      tags:
        - Customers
      summary: Get customer accounts
      description: Retrieves customer accounts by ID or origSystemReference.
      x-endpointsModeled: true
      responses:
        '200':
          description: A list of customer accounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerAccount'
    post:
      operationId: createCustomerAccount
      tags:
        - Customers
      summary: Create customer account
      description: Creates a customer account with partner and payment-term validation.
      x-endpointsModeled: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerAccount'
      responses:
        '200':
          description: The created customer account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerAccount'
  /invoices:
    post:
      operationId: createInvoice
      tags:
        - Invoices
      summary: Create or update invoice
      description: Creates or updates an invoice for manual AR integration.
      x-endpointsModeled: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Invoice'
      responses:
        '200':
          description: The created or updated invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
  /revenue/contract-amendment-setup:
    get:
      operationId: getRevenueContractAmendmentSetup
      tags:
        - Revenue Recognition
      summary: Get revenue contract amendment setup
      description: >-
        Retrieves ASC 606 performance-obligation (POB) and compliance
        configuration for revenue-contract amendments.
      x-endpointsModeled: true
      responses:
        '200':
          description: The revenue contract amendment setup.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevenueContractAmendmentSetup'
    post:
      operationId: createRevenueContractAmendmentSetup
      tags:
        - Revenue Recognition
      summary: Create revenue contract amendment setup
      description: Creates ASC 606 POB and compliance controls for a revenue contract.
      x-endpointsModeled: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevenueContractAmendmentSetup'
      responses:
        '200':
          description: The created setup.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevenueContractAmendmentSetup'
  /programs/execute:
    post:
      operationId: executeConcurrentProgram
      tags:
        - Programs
      summary: Execute concurrent program
      description: >-
        Asynchronously executes a background program - bill runs, revenue
        recognition, tax, and exports.
      x-endpointsModeled: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                programId:
                  type: string
                parameters:
                  type: object
                  additionalProperties: true
      responses:
        '202':
          description: Program accepted for asynchronous execution.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestId:
                    type: string
                  status:
                    type: string
components:
  securitySchemes:
    oauth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.recvue.com/api/v2.0/api/scim/oauth/token
          scopes: {}
  responses:
    Unauthorized:
      description: Authentication failed or token is missing/expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    AccessToken:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
        scope:
          type: string
    Order:
      type: object
      description: >-
        An order. RecVue orders carry hundreds of standard and custom fields;
        only a representative subset is modeled here.
      properties:
        orderId:
          type: string
        orderNumber:
          type: string
        externalReference:
          type: string
        orderType:
          type: string
        customerAccountNumber:
          type: string
        status:
          type: string
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        currency:
          type: string
        lines:
          type: array
          items:
            $ref: '#/components/schemas/OrderLine'
      additionalProperties: true
    OrderLine:
      type: object
      properties:
        lineId:
          type: string
        productId:
          type: string
        quantity:
          type: number
        unitPrice:
          type: number
        priceListId:
          type: string
        revenueFlag:
          type: boolean
      additionalProperties: true
    OrderList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        page:
          type: integer
        total:
          type: integer
    BillRun:
      type: object
      properties:
        billRunId:
          type: string
        name:
          type: string
        status:
          type: string
          enum: [CREATED, PROCESSING, COMPLETED]
        billingDate:
          type: string
          format: date
      additionalProperties: true
    BillingSchedule:
      type: object
      properties:
        scheduleId:
          type: string
        orderLineId:
          type: string
        billingDate:
          type: string
          format: date
        quantity:
          type: number
        amount:
          type: number
        contingencyFlag:
          type: boolean
      additionalProperties: true
    PriceList:
      type: object
      properties:
        priceListId:
          type: string
        name:
          type: string
        type:
          type: string
          enum: [STANDARD, CUSTOMER, REVENUE, HIERARCHICAL]
        items:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    UsageBatch:
      type: object
      properties:
        batchId:
          type: string
        records:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    Delivery:
      type: object
      properties:
        deliveryId:
          type: string
        orderLineId:
          type: string
        quantity:
          type: number
        deliveryDate:
          type: string
          format: date
        status:
          type: string
      additionalProperties: true
    CustomerAccount:
      type: object
      properties:
        accountNumber:
          type: string
        name:
          type: string
        origSystemReference:
          type: string
        paymentTerms:
          type: string
        sites:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    Invoice:
      type: object
      properties:
        invoiceNumber:
          type: string
        customerAccountNumber:
          type: string
        transactionType:
          type: string
          enum: [INV, CM, DM]
        amount:
          type: number
        glDate:
          type: string
          format: date
      additionalProperties: true
    RevenueContractAmendmentSetup:
      type: object
      properties:
        setupId:
          type: string
        performanceObligation:
          type: string
        allocationMethod:
          type: string
        complianceStandard:
          type: string
          enum: [ASC606, IFRS15]
      additionalProperties: true
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string