FUSE Health Orders API

openapi: 3.2.0
info:
  title: FUSE Brand API (External) Orders API
  version: 1.0.0
  description: 'Server-to-server API exposing the FUSE brand-admin surface so a single brand/tenant can build its own admin frontend. Every request is authenticated with an API key bound to exactly one clinic; all data is auto-scoped to that clinic and cannot reach another brand''s data. Isolation is enforced by application-layer clinic filtering on every query.


    COVERAGE: 218 operations across 180 paths, and EVERY ONE is available to every brand. There is no per-clinic enablement step. What governs access: your API key and its scopes, the clinic the key belongs to (every read and write is filtered to it), your plan''s entitlements for the two commercially-gated areas — Affiliates (`AFFILIATES_TIER_REQUIRED`) and CRM Connect (`CRM_TIER_REQUIRED`) — and rate limits.


    AUTH: the external /api/v1 surface uses an API key (`x-api-key`, ApiKeyAuth). Key management (/api-keys) and /auth/signin live at the API root and use a brand-admin JWT (BearerAuth); /auth/signin itself is unauthenticated.


    SCOPES: every key carries scopes; read-only is the default and mutating endpoints require the `write` scope (403 INSUFFICIENT_SCOPE otherwise). Keys default to a 1-year expiry.


    RATE LIMITING: every endpoint may additionally return `429 Too Many Requests` with a `Retry-After` header; 429 is not repeated on each operation below.


    PLATFORM FIELDS: product cost, fees, pharmacy routing, doctor questions and FUSE approvals are set by FUSE, not by the brand. Any write (POST/PUT/PATCH/DELETE) whose JSON body carries one of those fields at any depth — for example `pharmacyPrice`, `shippingFeeUsd`, `coolerFeeUsd`, `pharmacyId`, `preferredPharmacyId`, `pharmacyProvider`, `requiredDoctorQuestions`, `facilitationFee`, `placeholderPrice`, `legalBusinessName`, `isTemplate` or `tenantManagerApproved` — is refused with `403 PLATFORM_FIELD`, whose `fields` array lists the offending paths; remove them and resend. (One exception: `POST /api/v1/products` still accepts the `pharmacyPrice` its schema requires, and ignores it.) 403 PLATFORM_FIELD is not repeated on each operation below.'
servers:
- url: https://api-dev.fusehealth.com
  description: Development
- url: https://api.fusehealth.com
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Orders
paths:
  /api/v1/orders:
    get:
      tags:
      - Orders
      summary: Paginated orders. Each row includes the per-order feeBreakdown
      operationId: getApiV1Orders
      description: Paginated orders. Each row includes the per-order feeBreakdown.
      security:
      - ApiKeyAuth: []
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
        example: '1'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 25
        example: '25'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/orders/stats:
    get:
      tags:
      - Orders
      summary: Aggregate order + earnings stats
      operationId: getApiV1OrdersStats
      description: Aggregate order + earnings stats.
      security:
      - ApiKeyAuth: []
      parameters:
      - name: startDate
        in: query
        required: false
        schema:
          type: string
        example: '2026-01-01'
      - name: endDate
        in: query
        required: false
        schema:
          type: string
        example: '2026-12-31'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/orders/summary:
    get:
      tags:
      - Orders
      summary: Aggregate order breakdowns — by status, program, shipping state, and refunds…
      operationId: getApiV1OrdersSummary
      description: 'Counts and sums only: orders by status, orders and paid sales by program, orders by shipping state, and refund requests by status with the approved total. Never returns an order id, order number, date, patient or medication. A shipping state with fewer than 5 orders is never named; all such states are reported together in `otherStates`. Safe for the AI connector.'
      security:
      - ApiKeyAuth: []
      parameters:
      - name: startDate
        in: query
        required: false
        schema:
          type: string
        example: '2026-01-01'
      - name: endDate
        in: query
        required: false
        schema:
          type: string
        example: '2026-12-31'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      window:
                        type: object
                        properties:
                          startDate:
                            type:
                            - string
                            - 'null'
                          endDate:
                            type:
                            - string
                            - 'null'
                      totalOrders:
                        type: integer
                      byStatus:
                        type: array
                        items:
                          type: object
                          properties:
                            status:
                              type: string
                            orders:
                              type: integer
                      byProgram:
                        type: array
                        items:
                          type: object
                          properties:
                            programId:
                              type:
                              - string
                              - 'null'
                            programName:
                              type:
                              - string
                              - 'null'
                            orders:
                              type: integer
                            paidSales:
                              type: number
                      byState:
                        type: array
                        description: Only states with 5 or more orders.
                        items:
                          type: object
                          properties:
                            state:
                              type: string
                            orders:
                              type: integer
                      otherStates:
                        type:
                        - object
                        - 'null'
                        description: States with fewer than 5 orders, unnamed — how many, and their orders together.
                        properties:
                          states:
                            type: integer
                          orders:
                            type: integer
                      refunds:
                        type: object
                        properties:
                          byStatus:
                            type: array
                            items:
                              type: object
                              properties:
                                status:
                                  type: string
                                requests:
                                  type: integer
                          approvedAmount:
                            type: number
        '400':
          description: Invalid startDate or endDate
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/orders/{id}:
    get:
      tags:
      - Orders
      summary: Order detail with the full fee waterfall (matches the brand-admin UI)
      operationId: getApiV1OrdersById
      description: Order detail with the full fee waterfall (matches the brand-admin UI).
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/OrderBrandView'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/orders/{id}/events:
    get:
      tags:
      - Orders
      summary: Chronological status/event timeline for one order
      operationId: getApiV1OrdersByIdEvents
      description: Chronological status/event timeline for one order.
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      events:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            eventType:
                              type: string
                            actorType:
                              type: string
                            createdAt:
                              type: string
                              format: date-time
                            metadata:
                              type: object
                      hasPrescriptionPdf:
                        type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/orders/{id}/lab-status:
    get:
      tags:
      - Orders
      summary: Lab lifecycle state and lab-kit tracking for one order
      operationId: getApiV1OrdersByIdLabStatus
      description: 'Lab lifecycle STATE for one of the key clinic''s orders: the current stage, a stage-by-stage timeline with timestamps, and the lab-kit shipment carrier/tracking numbers for both legs (FUSE to patient, patient to lab).


        This endpoint deliberately exposes NO lab result content — no analyte values, reference ranges, interpretations, result documents, requisition PDFs, or results-review booking links. `resultsAvailableAt` is a timestamp only: it tells you the lab has reported, not what it reported.


        Requires the `v1_fulfillment` endpoint group to be enabled for your clinic (contact FUSE). Returns 404 for an unknown, malformed, or another clinic''s order id.'
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Order id (UUID). Must belong to the API key's clinic.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      orderId:
                        type: string
                        format: uuid
                      isLabGated:
                        type: boolean
                        description: Whether this order uses the lab-gated split-payment flow.
                      orderStatus:
                        type:
                        - string
                        - 'null'
                        description: The order's overall status. Lab-related values include `awaiting_lab_results`, `awaiting_renewal_lab`, `authorization_failed`, `authorized_awaiting_review`.
                      stage:
                        type:
                        - string
                        - 'null'
                        description: Current lab lifecycle stage; `null` when the order has no lab leg yet.
                        enum:
                        - requisition_created
                        - shipped_to_patient
                        - delivered_to_patient
                        - shipped_to_lab
                        - received_by_lab
                        - results
                        - null
                      timeline:
                        type: array
                        description: All six stages in lifecycle order. `reached` is true for the current stage and every stage before it. `occurredAt` is null for unreached stages and for the two shipment stages, which carry carrier/tracking but no dedicated timestamp.
                        items:
                          type: object
                          properties:
                            stage:
                              type: string
                              enum:
                              - requisition_created
                              - shipped_to_patient
                              - delivered_to_patient
                              - shipped_to_lab
                              - received_by_lab
                              - results
                            reached:
                              type: boolean
                            occurredAt:
                              type:
                              - string
                              - 'null'
                              format: date-time
                      kitShipmentToPatient:
                        type: object
                        description: Outbound leg — lab kit shipped to the patient.
                        properties:
                          carrier:
                            type:
                            - string
                            - 'null'
                          trackingNumber:
                            type:
                            - string
                            - 'null'
                          deliveredAt:
                            type:
                            - string
                            - 'null'
                            format: date-time
                      kitShipmentToLab:
                        type: object
                        description: Return leg — patient's sample shipped to the lab.
                        properties:
                          carrier:
                            type:
                            - string
                            - 'null'
                          trackingNumber:
                            type:
                            - string
                            - 'null'
                          receivedAt:
                            type:
                            - string
                            - 'null'
                            format: date-time
                      resultsAvailableAt:
                        type:
                        - string
                        - 'null'
                        format: date-time
                        description: When the lab reported results. TIMESTAMP ONLY — the result content itself is never exposed on this API.
              example:
                success: true
                data:
                  orderId: 8f14e45f-ceea-467a-9b2b-1c0a1d0e2f30
                  isLabGated: true
                  orderStatus: awaiting_lab_results
                  stage: received_by_lab
                  timeline:
                  - stage: requisition_created
                    reached: true
                    occurredAt: '2026-04-01T10:00:00.000Z'
                  - stage: shipped_to_patient
                    reached: true
                    occurredAt: null
                  - stage: delivered_to_patient
                    reached: true
                    occurredAt: '2026-04-03T10:00:00.000Z'
                  - stage: shipped_to_lab
                    reached: true
                    occurredAt: null
                  - stage: received_by_lab
                    reached: true
                    occurredAt: '2026-04-07T10:00:00.000Z'
                  - stage: results
                    reached: false
                    occurredAt: null
                  kitShipmentToPatient:
                    carrier: UPS
                    trackingNumber: 1Z999AA10123456784
                    deliveredAt: '2026-04-03T10:00:00.000Z'
                  kitShipmentToLab:
                    carrier: FedEx
                    trackingNumber: '774899999999'
                    receivedAt: '2026-04-07T10:00:00.000Z'
                  resultsAvailableAt: null
        '403':
          description: The `v1_fulfillment` endpoint group is not enabled for your clinic
        '404':
          description: Order not found. Returned for an unknown id, a malformed (non-UUID) id, and an id belonging to another clinic — the three are deliberately indistinguishable.
  /api/v1/orders/{id}/visit-status:
    get:
      tags:
      - Orders
      summary: Telehealth visit status and appointment time for one order
      operationId: getApiV1OrdersByIdVisitStatus
      description: 'Whether the patient has booked their live (synchronous) visit, has not booked yet, or did not attend — plus the appointment time when one is scheduled. This is the read side of the `appointment.scheduled` / `appointment.cancelled` webhooks: those notify you that something changed and carry ids only, and this endpoint tells you what the state now is.


        `visitStatus` is a FUSE-defined value, deliberately independent of any doctor network''s internal naming, so it is stable across changes FUSE makes behind the scenes. Treat it as a closed set and handle an unrecognised value defensively.


        Before chasing a patient to book, check `bookingRequired`. Asynchronous treatments never require a live appointment and rest permanently at `not_booked` — that is normal, not an outstanding task. `bookingRequired` is `null` when the order predates visit-type resolution (unknown, not "no appointment needed").


        This endpoint exposes NO clinical content: no prescriber name, NPI or phone, no prescribed medications, no visit outcome, and no lab results. A referred visit is already visible via the order''s own `status`.


        Requires the `v1_fulfillment` endpoint group to be enabled for your clinic (contact FUSE). Returns 404 for an unknown, malformed, or another clinic''s order id.'
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Order id (UUID). Must belong to the API key's clinic.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      orderId:
                        type: string
                        format: uuid
                      visitStatus:
                        type: string
                        description: '`not_booked` — no live appointment is confirmed. Either the patient has not booked yet, or the treatment is asynchronous in their state and never requires one (check `bookingRequired`).

                          `booked` — a live visit is confirmed; see `scheduledAt`.

                          `no_show` — the patient did not attend the confirmed appointment.

                          `concluded` — the visit is complete (consult finished and/or prescription written); no further patient action is needed.

                          `cancelled` — the visit was cancelled; FUSE cancels the order alongside it, so the order''s own status reflects it too.'
                        enum:
                        - not_booked
                        - booked
                        - no_show
                        - concluded
                        - cancelled
                      bookingRequired:
                        type:
                        - boolean
                        - 'null'
                        description: Whether this order's visit type requires a live appointment at all. `false` for asynchronous treatments. `null` when the order predates visit-type resolution — unknown, NOT "no appointment needed".
                      scheduledAt:
                        type:
                        - string
                        - 'null'
                        format: date-time
                        description: The appointment time, when the doctor network supplied one. Retained after a `no_show` (it is the appointment that was missed). `null` whenever no appointment has been scheduled.
                      lastSyncedAt:
                        type:
                        - string
                        - 'null'
                        format: date-time
                        description: When the doctor network last sent FUSE any update about this visit. Use it to tell "no appointment has been booked" apart from "we have not heard anything recently" — a stale value on an order you expect to be progressing is worth raising with FUSE.
              example:
                success: true
                data:
                  orderId: 8f14e45f-ceea-467a-9b2b-1c0a1d0e2f30
                  visitStatus: booked
                  bookingRequired: true
                  scheduledAt: '2026-08-03T15:30:00.000Z'
                  lastSyncedAt: '2026-08-01T09:00:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The `v1_fulfillment` endpoint group is not enabled for your clinic
        '404':
          description: Order not found. Returned for an unknown id, a malformed (non-UUID) id, and an id belonging to another clinic — the three are deliberately indistinguishable.
  /api/v1/orders/needs-attention:
    get:
      tags:
      - Orders
      summary: List orders needing attention (failed payment / dunning queue)
      operationId: getApiV1OrdersNeedsattention
      description: 'The dunning queue: this clinic''s orders in `payment_due` whose most recent charge failed, enriched with Stripe retry context. Clinic-scoped by the API key. PHI: patient first/last name only (data-minimized). Read scope.'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      count:
                        type: integer
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            orderId:
                              type: string
                              format: uuid
                            orderNumber:
                              type: string
                            patientName:
                              type:
                              - string
                              - 'null'
                            programName:
                              type:
                              - string
                              - 'null'
                            paymentFailedAt:
                              type:
                              - string
                              - 'null'
                              format: date-time
                            lastPaymentError:
                              type:
                              - string
                              - 'null'
                            enrichment:
                              type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Missing, invalid, inactive, or expired API key (or JWT)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: Resource not found (or not owned by the key's clinic)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  schemas:
    OrderBrandView:
      description: Sanitized brand-facing order (whitelisted fields only).
      type: object
      properties:
        id:
          type: string
          format: uuid
        orderNumber:
          type: string
        status:
          type: string
        totalAmount:
          type: number
        subtotalAmount:
          type: number
        discountAmount:
          type: number
        taxAmount:
          type: number
        shippingAmount:
          type: number
        brandAmount:
          type: number
        billingInterval:
          type: string
        createdAt:
          type: string
          format: date-time
        shippedAt:
          type:
          - string
          - 'null'
          format: date-time
        deliveredAt:
          type:
          - string
          - 'null'
          format: date-time
        fulfillmentType:
          type: string
        approvedByDoctor:
          type: boolean
        feeBreakdown:
          type: object
          additionalProperties: true
          description: Per-order fee waterfall.
        user:
          type: object
          properties:
            id:
              type: string
              format: uuid
            firstName:
              type: string
            lastName:
              type: string
            email:
              type: string
            phoneNumber:
              type:
              - string
              - 'null'
        orderItems:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              quantity:
                type: integer
              unitPrice:
                type: number
              totalPrice:
                type: number
              product:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  name:
                    type: string
        payment:
          type: object
          properties:
            status:
              type: string
            paymentMethod:
              type: string
        shippingAddress:
          type: object
          properties:
            address:
              type: string
            city:
              type: string
            state:
              type: string
            zipCode:
              type: string
            country:
              type: string
        shippingOrders:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              status:
                type: string
              trackingNumber:
                type:
                - string
                - 'null'
              trackingUrl:
                type:
                - string
                - 'null'
    ErrorEnvelope:
      description: 'Failure shape. NOTE: most modules use `message`; programs endpoints use `error`. Read both. Some errors include a machine-readable `code` and/or a `data` payload.'
      type: object
      properties:
        success:
          type: boolean
          enum:
          - false
        message:
          type: string
        error:
          type: string
        code:
          type: string
        data: {}
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Clinic-scoped API key. Keep server-side; never expose in a browser or app bundle.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: FUSE brand-admin JWT (from POST /auth/signin). Used ONLY by the key-management endpoints — the external /api/v1 surface never accepts JWTs, and API keys never work on key management.