openapi: 3.2.0
info:
  title: Cacheflow Proposal Deltas API
  version: 0.0.3
servers:
- url: https://api.getcacheflow.com
  description: 'Production. Calls are tenant-routed: send Host: <org-flow-domain>.api.getcacheflow.com (per github.com/getcacheflow/api-examples SETUP.md). Host no longer resolves as of 2026-08-13.'
- url: https://api.sandbox.getcacheflow.com
  description: Sandbox. Tenant-routed as <org-flow-domain>.api.sandbox.getcacheflow.com. Host no longer resolves as of 2026-08-13.
tags:
- name: Proposal Deltas
paths:
  /api/latest/proposals/{id}/delta-spans:
    get:
      tags:
      - Proposal Deltas
      summary: Retrieve proposal delta spans
      operationId: getProposalDeltaSpans
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: email
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ItemDeltaSpansResponse'
components:
  schemas:
    ItemDeltaSpansResponse:
      required:
      - item
      - spans
      type: object
      properties:
        item:
          $ref: '#/components/schemas/Item'
        spans:
          type: array
          items:
            $ref: '#/components/schemas/LineItemSpan'
    Money:
      type: object
      properties:
        amount:
          type: integer
          format: int64
        scale:
          type: integer
          format: int32
        formattedAmount:
          type: string
        currency:
          type: string
      description: Total list amount for this level. null for usage.
    ItemOverride:
      required:
      - discount
      type: object
      properties:
        billingPeriod:
          type: string
          enum:
          - month
          - quarter
          - halfyear
          - year
        discount:
          type: boolean
        duration:
          type: integer
          format: int32
        startIndex:
          type: integer
          format: int32
        price:
          $ref: '#/components/schemas/Money'
        listPrice:
          $ref: '#/components/schemas/Money'
        levels:
          type: array
          items:
            $ref: '#/components/schemas/ItemLevelOverride'
    LineItemLevel:
      type: object
      properties:
        quantity:
          type: number
        visible:
          type: boolean
        start:
          type: integer
          format: int32
        unitPricing:
          $ref: '#/components/schemas/Money'
        baseUnitPricing:
          $ref: '#/components/schemas/Money'
    PricebookEntry:
      required:
      - price
      type: object
      properties:
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
          readOnly: true
        createdBy:
          type: string
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        updatedBy:
          type: string
          readOnly: true
        billingPeriod:
          type: string
          enum:
          - month
          - quarter
          - halfyear
          - year
        level:
          type: integer
          format: int32
        price:
          $ref: '#/components/schemas/Money'
    Product:
      required:
      - billing
      - consumption
      - createdAt
      - customizable
      - discountable
      - displayQuantityOnInvoicePdf
      - entries
      - extendedScale
      - hidden
      - id
      - listPriceAdjustable
      - pricing
      - productType
      - recurrence
      - status
      - updatedAt
      type: object
      properties:
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        createdBy:
          type: string
        updatedAt:
          type: string
          format: date-time
        updatedBy:
          type: string
        sources:
          type: array
          items:
            $ref: '#/components/schemas/ExternalSource'
        hidden:
          type: boolean
        rootId:
          type: string
          format: uuid
        productType:
          type: string
          enum:
          - single
          - bundleTopDown
          - bundleBottomUp
        status:
          type: string
          enum:
          - active
          - inactive
        name:
          type: string
        internalName:
          type: string
        description:
          type: string
        recurrence:
          type: string
          enum:
          - one_time
          - recurring
          - usage
        pricing:
          type: string
          enum:
          - fixed
          - graduated
          - stairstep
          - volume
        consumption:
          type: string
          enum:
          - single
          - multiple
        billing:
          type: string
          enum:
          - scheduled
          - fixed
        unit:
          $ref: '#/components/schemas/Unit'
        extendedScale:
          type: boolean
        customizable:
          type: boolean
        discountable:
          type: boolean
        displayQuantityOnInvoicePdf:
          type: boolean
        listPriceAdjustable:
          type: boolean
        descriptionCustomizable:
          type: boolean
        nameCustomizable:
          type: boolean
        billingPeriods:
          type: array
          items:
            type: string
            enum:
            - month
            - quarter
            - halfyear
            - year
        currencies:
          type: array
          items:
            type: string
        taxConfig:
          $ref: '#/components/schemas/ProductTaxConfig'
        entries:
          type: array
          items:
            $ref: '#/components/schemas/PricebookEntry'
        levels:
          type: array
          items:
            $ref: '#/components/schemas/ProductLevel'
        showProductsOnInvoice:
          type: boolean
        showProductPricesOnInvoice:
          type: boolean
        showProductsOnProposal:
          type: boolean
        bundleItems:
          type: array
          items:
            $ref: '#/components/schemas/BundleItem'
        bundleBottomUpEntries:
          type: array
          items:
            $ref: '#/components/schemas/BundlePriceEntry'
        bundleGroups:
          type: array
          items:
            type: string
    BundleItem:
      required:
      - entries
      - id
      - name
      - product
      type: object
      properties:
        id:
          type: string
          format: uuid
        product:
          $ref: '#/components/schemas/Product'
        quantity:
          type: number
        bundlePercent:
          type: integer
          format: int32
        entries:
          type: array
          items:
            $ref: '#/components/schemas/BundlePriceEntry'
        name:
          type: string
        description:
          type: string
    ItemSchedule:
      required:
      - productId
      - startDate
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
        createdBy:
          type: string
        updatedAt:
          type: string
          format: date-time
        updatedBy:
          type: string
        id:
          type: string
          format: uuid
        productId:
          type: string
          description: Product id for a specific version of the product. Must have the same root as the parent Item.
          format: uuid
        billingPeriod:
          type: string
          description: Billing period context.
          enum:
          - month
          - quarter
          - halfyear
          - year
        startIndex:
          type: integer
          description: Regular payment start index.
          format: int32
        endIndex:
          type: integer
          description: Inclusive regular payment end index.
          format: int32
        startDate:
          type: string
          description: Absolute start date. Absolute date when scheduled is true, otherwise calculated.
          format: date
        endDate:
          type: string
          description: Inclusive absolute end date. Absolute date when scheduled is true, otherwise null.
          format: date
        scheduled:
          type: boolean
          description: Indicates schedule has explicitly scheduled dates.
        price:
          $ref: '#/components/schemas/Money'
        basePrice:
          $ref: '#/components/schemas/Money'
        listPrice:
          $ref: '#/components/schemas/Money'
        amount:
          $ref: '#/components/schemas/Money'
        baseAmount:
          $ref: '#/components/schemas/Money'
        listAmount:
          $ref: '#/components/schemas/Money'
        quantity:
          type: number
        discount:
          type: boolean
        levels:
          type: array
          items:
            $ref: '#/components/schemas/ItemScheduleLevel'
    ExternalSource:
      required:
      - sourceId
      - sourceType
      type: object
      properties:
        sourceType:
          type: string
          enum:
          - manual
          - close
          - plaid
          - stripe
          - hubspot
          - salesforce
          - avalara
          - quickbooks
          - profitwell
          - netsuite
          - google
          - warmly
          - zapier
          - cacheflow_checkout
        sourceId:
          type: string
        sourceLink:
          type: string
    ProductTaxConfig:
      type: object
      properties:
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
          readOnly: true
        createdBy:
          type: string
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        updatedBy:
          type: string
          readOnly: true
        taxMode:
          type: string
          enum:
          - inclusive
          - exclusive
        taxCode:
          $ref: '#/components/schemas/TaxCode'
    Item:
      required:
      - createdAt
      - customized
      - customizedLevels
      - groups
      - id
      - key
      - product
      - schedules
      - spans
      - updatedAt
      - updatedBy
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
        createdBy:
          type: string
        updatedAt:
          type: string
          format: date-time
        updatedBy:
          type: string
        id:
          type: string
          format: uuid
        key:
          type: string
          format: uuid
        quantity:
          type: number
        product:
          $ref: '#/components/schemas/Product'
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        name:
          type: string
        description:
          type: string
        descriptionText:
          type: string
        customized:
          type: boolean
        customizedLevels:
          type: boolean
        levels:
          type: array
          items:
            $ref: '#/components/schemas/ItemLevel'
        overrides:
          type: array
          items:
            $ref: '#/components/schemas/ItemOverride'
        quantityOverrides:
          type: array
          items:
            $ref: '#/components/schemas/QuantityOverride'
        spans:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/LineItemSpan'
        schedules:
          type: array
          items:
            $ref: '#/components/schemas/ItemSchedule'
        groups:
          type: array
          items:
            $ref: '#/components/schemas/SpanGroup'
        levelVisibility:
          type: string
          enum:
          - all
          - active
          - active_plus_one
          - active_plus_three
          - active_plus_prior_next
          - active_plus_prior_next_three
    TaxCode:
      type: object
      properties:
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
          readOnly: true
        createdBy:
          type: string
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        updatedBy:
          type: string
          readOnly: true
        code:
          type: string
        description:
          type: string
    Duration:
      required:
      - days
      - months
      type: object
      properties:
        months:
          type: integer
          format: int32
        days:
          type: integer
          format: int32
    ItemScheduleLevel:
      required:
      - basePrice
      - level
      - listPrice
      - price
      - start
      type: object
      properties:
        level:
          type: integer
          description: Level index, 0-based
          format: int32
        start:
          type: integer
          description: Level start value
          format: int32
        quantity:
          type: number
          description: Portion of ItemSchedule quantity assigned to this level. null for usage
        price:
          $ref: '#/components/schemas/Money'
        listPrice:
          $ref: '#/components/schemas/Money'
        basePrice:
          $ref: '#/components/schemas/Money'
        amount:
          $ref: '#/components/schemas/Money'
        baseAmount:
          $ref: '#/components/schemas/Money'
        listAmount:
          $ref: '#/components/schemas/Money'
    ItemLevelOverride:
      required:
      - level
      - price
      type: object
      properties:
        level:
          type: integer
          format: int32
        price:
          $ref: '#/components/schemas/Money'
        listPrice:
          $ref: '#/components/schemas/Money'
    QuantityOverride:
      required:
      - billingPeriod
      - quantity
      type: object
      properties:
        billingPeriod:
          type: string
          enum:
          - month
          - quarter
          - halfyear
          - year
        quantity:
          type: number
        startIndex:
          type: integer
          format: int32
        duration:
          type: integer
          format: int32
    Unit:
      type: object
      properties:
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
          readOnly: true
        createdBy:
          type: string
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        updatedBy:
          type: string
          readOnly: true
        name:
          type: string
        plural:
          type: string
    LineItemSpan:
      required:
      - amount
      - baseAmount
      - listAmount
      - proposalId
      - proratedTotalAmount
      - proratedTotalListAmount
      - spanType
      type: object
      properties:
        spanType:
          type: string
          enum:
          - regular
          - free
          - removed
        proposalId:
          type: string
          format: uuid
        itemScheduleId:
          type: string
          format: uuid
        startIndex:
          type: integer
          format: int32
          deprecated: true
        duration:
          type: integer
          format: int32
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        quantity:
          type: number
        levels:
          type: array
          items:
            $ref: '#/components/schemas/LineItemLevel'
        durationDesc:
          $ref: '#/components/schemas/Duration'
        baseAmount:
          $ref: '#/components/schemas/Money'
        amount:
          $ref: '#/components/schemas/Money'
        listAmount:
          $ref: '#/components/schemas/Money'
        discount:
          $ref: '#/components/schemas/Money'
        discountPercent:
          type: integer
          format: int32
        prorating:
          type: number
        fullDays:
          type: integer
          format: int32
        proratedDays:
          type: integer
          format: int32
        proratedAmount:
          $ref: '#/components/schemas/Money'
        proratedBaseAmount:
          $ref: '#/components/schemas/Money'
        proratedListAmount:
          $ref: '#/components/schemas/Money'
        proratedTotalListAmount:
          $ref: '#/components/schemas/Money'
        proratedTotalAmount:
          $ref: '#/components/schemas/Money'
        unitPricing:
          $ref: '#/components/schemas/Money'
        baseUnitPricing:
          $ref: '#/components/schemas/Money'
        unitPricingDiscount:
          $ref: '#/components/schemas/Money'
        groupId:
          type: integer
          format: int32
    ItemLevel:
      required:
      - index
      - start
      - visible
      type: object
      properties:
        index:
          type: integer
          format: int32
        start:
          type: integer
          format: int32
        hidden:
          type: boolean
        visibilityOverride:
          type: boolean
        visible:
          type: object
          additionalProperties:
            type: boolean
    SpanGroup:
      required:
      - days
      - durationDesc
      - endDate
      - id
      - listTotal
      - proposalId
      - spanType
      - startDate
      - total
      type: object
      properties:
        id:
          type: integer
          format: int32
        spanType:
          type: string
          enum:
          - regular
          - free
          - removed
        proposalId:
          type: string
          format: uuid
        itemScheduleId:
          type: string
          format: uuid
        billingPeriod:
          type: string
          enum:
          - month
          - quarter
          - halfyear
          - year
        quantity:
          type: number
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        days:
          type: integer
          format: int32
        durationDesc:
          $ref: '#/components/schemas/Duration'
        total:
          $ref: '#/components/schemas/Money'
        listTotal:
          $ref: '#/components/schemas/Money'
        unitPricing:
          $ref: '#/components/schemas/Money'
        amount:
          $ref: '#/components/schemas/Money'
    BundlePriceEntry:
      required:
      - price
      type: object
      properties:
        billingPeriod:
          type: string
          enum:
          - month
          - quarter
          - halfyear
          - year
        price:
          $ref: '#/components/schemas/Money'
    ProductLevel:
      required:
      - start
      type: object
      properties:
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
          readOnly: true
        createdBy:
          type: string
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        updatedBy:
          type: string
          readOnly: true
        start:
          type: integer
          format: int32