openapi: 3.2.0
info:
  title: Cacheflow Refunds 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: Refunds
paths:
  /api/latest/data/refunds:
    get:
      tags:
      - Refunds
      summary: List Refunds
      operationId: listRefunds
      parameters:
      - name: search
        in: query
        schema:
          type: string
      - name: sort
        in: query
        schema:
          type: string
      - name: page
        in: query
        schema:
          type: integer
          format: int32
          default: 0
      - name: size
        in: query
        schema:
          type: integer
          format: int32
          default: 300
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Refund'
    post:
      tags:
      - Refunds
      summary: Schedule a refund for a transfer
      operationId: createRefund
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRefundRequest'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
  /api/latest/data/refunds/{refundId}:
    get:
      tags:
      - Refunds
      summary: Get Refund by ID
      operationId: getRefund
      parameters:
      - name: refundId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
  /api/latest/data/refunds/{refundId}/activity:
    get:
      tags:
      - Refunds
      summary: Get Refund activity by ID
      operationId: getRefundActivity
      parameters:
      - name: refundId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ActivityEvent'
  /api/latest/data/refunds/{refundId}/events:
    get:
      tags:
      - Refunds
      summary: Get Refund events by ID
      operationId: getRefundEvents
      parameters:
      - name: refundId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ActivityEvent'
      deprecated: true
  /api/latest/data/refunds/{refundId}/sync:
    post:
      tags:
      - Refunds
      summary: Get Refund activity by ID
      operationId: syncRefund
      parameters:
      - name: refundId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
components:
  schemas:
    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
    Customer:
      required:
      - createdAt
      - deleted
      - id
      - name
      - 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'
        name:
          type: string
        tin:
          type: string
        defaultCurrency:
          type: string
        billingAddress:
          $ref: '#/components/schemas/Address'
        shippingAddress:
          $ref: '#/components/schemas/Address'
        billingContact:
          $ref: '#/components/schemas/Contact'
        deleted:
          type: boolean
        taxUseCode:
          type: string
          enum:
          - A
          - B
          - C
          - D
          - E
          - F
          - G
          - H
          - I
          - J
          - K
          - L
          - M
          - N
          - P
          - Q
          - R
        partner:
          type: boolean
        referenceType:
          type: string
          enum:
          - account
          - apiwebhook
          - apitoken
          - approvalgroup
          - attachmentconfig
          - authidentity
          - billingschedule
          - companyInfo
          - connectorSyncEvent
          - contact
          - contentTemplate
          - contract
          - contractitem
          - contractitemlevel
          - currency
          - customer
          - docusignaccount
          - document
          - documentversion
          - group
          - invite
          - invoice
          - invoiceConfiguration
          - organization
          - orgconfig
          - orgidentitytoken
          - payment
          - paymentMethod
          - paymentSchedule
          - paymentTerm
          - pricebook
          - pricebookentry
          - product
          - productlevel
          - productusage
          - proposal
          - proposalapprovalrule
          - proposalevent
          - proposalitem
          - proposaliteminterval
          - proposalitemlevel
          - proposaloption
          - refund
          - renewalconfiguration
          - signature
          - signingdocument
          - transfer
          - transferevent
          - unit
          - user
        taxExempt:
          type: boolean
        syncable:
          type: boolean
    Address:
      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
        type:
          type: string
        streetAddress:
          type: string
        subAddress:
          type: string
        otherAddress:
          type: string
        city:
          type: string
        region:
          type: string
        regionIso:
          type: string
        postalCode:
          type: string
        country:
          type: string
        countryIso:
          type: string
        verifiedAt:
          type: string
          format: date-time
    ActivityEvent:
      type: object
      properties:
        id:
          type: string
          format: uuid
        actor:
          $ref: '#/components/schemas/ActivityActor'
        eventType:
          type: string
          enum:
          - transfer
          - integration
          - notification
          - record_changed
          - created
        eventCode:
          type: string
        details:
          $ref: '#/components/schemas/ActivityDetails'
        createdAt:
          type: string
          format: date-time
    ActivityActor:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        system:
          type: boolean
        identifier:
          type: string
    ObjectReference:
      type: object
      properties:
        referenceType:
          type: string
          enum:
          - account
          - apiwebhook
          - apitoken
          - approvalgroup
          - attachmentconfig
          - authidentity
          - billingschedule
          - companyInfo
          - connectorSyncEvent
          - contact
          - contentTemplate
          - contract
          - contractitem
          - contractitemlevel
          - currency
          - customer
          - docusignaccount
          - document
          - documentversion
          - group
          - invite
          - invoice
          - invoiceConfiguration
          - organization
          - orgconfig
          - orgidentitytoken
          - payment
          - paymentMethod
          - paymentSchedule
          - paymentTerm
          - pricebook
          - pricebookentry
          - product
          - productlevel
          - productusage
          - proposal
          - proposalapprovalrule
          - proposalevent
          - proposalitem
          - proposaliteminterval
          - proposalitemlevel
          - proposaloption
          - refund
          - renewalconfiguration
          - signature
          - signingdocument
          - transfer
          - transferevent
          - unit
          - user
        id:
          type: string
          format: uuid
        uri:
          type: string
        name:
          type: string
        type:
          type: string
          writeOnly: true
          enum:
          - account
          - apiwebhook
          - apitoken
          - approvalgroup
          - attachmentconfig
          - authidentity
          - billingschedule
          - companyInfo
          - connectorSyncEvent
          - contact
          - contentTemplate
          - contract
          - contractitem
          - contractitemlevel
          - currency
          - customer
          - docusignaccount
          - document
          - documentversion
          - group
          - invite
          - invoice
          - invoiceConfiguration
          - organization
          - orgconfig
          - orgidentitytoken
          - payment
          - paymentMethod
          - paymentSchedule
          - paymentTerm
          - pricebook
          - pricebookentry
          - product
          - productlevel
          - productusage
          - proposal
          - proposalapprovalrule
          - proposalevent
          - proposalitem
          - proposaliteminterval
          - proposalitemlevel
          - proposaloption
          - refund
          - renewalconfiguration
          - signature
          - signingdocument
          - transfer
          - transferevent
          - unit
          - user
    Refund:
      required:
      - amount
      - amountFormatted
      - createdAt
      - id
      - processDate
      - status
      - transfer
      - 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'
        amount:
          type: integer
          format: int64
        amountFormatted:
          type: string
        processDate:
          type: string
          format: date
        status:
          type: string
          enum:
          - pending
          - in_progress
          - posted
          - failed
          - cancelled
          - reversed
        transferStatus:
          type: string
          enum:
          - pending
          - in_progress
          - failed
          - posted
          - cancelled
          - declined
          - reversed
          - receiver_pending
          - receiver_posted
        transfer:
          $ref: '#/components/schemas/Transfer'
        customer:
          $ref: '#/components/schemas/Customer'
        note:
          type: string
        lastSyncEvent:
          $ref: '#/components/schemas/SyncEvent'
    Transfer:
      required:
      - amount
      - currency
      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
        processedAt:
          type: string
          format: date-time
        externalId:
          type: string
        currency:
          type: string
        amount:
          type: integer
          format: int64
        paidAmount:
          type: integer
          format: int64
        fromAccount:
          $ref: '#/components/schemas/Account'
        referenceTransferId:
          type: string
          format: uuid
        fromAccountId:
          type: string
          format: uuid
          writeOnly: true
        toAccount:
          $ref: '#/components/schemas/Account'
        toAccountId:
          type: string
          format: uuid
          writeOnly: true
        reason:
          type: string
        parentReferenceId:
          type: string
          format: uuid
        parentReferenceType:
          type: string
          enum:
          - account
          - apiwebhook
          - apitoken
          - approvalgroup
          - attachmentconfig
          - authidentity
          - billingschedule
          - companyInfo
          - connectorSyncEvent
          - contact
          - contentTemplate
          - contract
          - contractitem
          - contractitemlevel
          - currency
          - customer
          - docusignaccount
          - document
          - documentversion
          - group
          - invite
          - invoice
          - invoiceConfiguration
          - organization
          - orgconfig
          - orgidentitytoken
          - payment
          - paymentMethod
          - paymentSchedule
          - paymentTerm
          - pricebook
          - pricebookentry
          - product
          - productlevel
          - productusage
          - proposal
          - proposalapprovalrule
          - proposalevent
          - proposalitem
          - proposaliteminterval
          - proposalitemlevel
          - proposaloption
          - refund
          - renewalconfiguration
          - signature
          - signingdocument
          - transfer
          - transferevent
          - unit
          - user
        status:
          type: string
          enum:
          - pending
          - in_progress
          - failed
          - posted
          - cancelled
          - declined
          - reversed
          - receiver_pending
          - receiver_posted
        type:
          type: string
          enum:
          - DEBIT
          - CREDIT
        processor:
          type: string
          enum:
          - plaid
          - stripe
          - manual
        paymentType:
          type: string
          deprecated: true
          enum:
          - ach
          - cc
          - check
          - custom
          - direct_debit
          - wire
          - external
          - manual
        category:
          type: string
          enum:
          - FEE
          - PAYMENT
          - PAYOUT
          - REFUND
          - ADJUSTMENT
        reasonCode:
          type: string
          enum:
          - invalid_account
          - insufficient_funds
          - flagged_account
          - region_not_supported
          - invalid_address
          - requires_buyer_approval
          - transaction_failure
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
        achType:
          type: string
          enum:
          - arc
          - cbr
          - ccd
          - cie
          - cor
          - ctx
          - iat
          - mte
          - pbr
          - pop
          - pos
          - ppd
          - rck
          - tel
          - web
        failures:
          type: integer
          format: int32
        retryAt:
          type: string
          format: date-time
        referenceNumber:
          type: string
        referenceType:
          type: string
          enum:
          - account
          - apiwebhook
          - apitoken
          - approvalgroup
          - attachmentconfig
          - authidentity
          - billingschedule
          - companyInfo
          - connectorSyncEvent
          - contact
          - contentTemplate
          - contract
          - contractitem
          - contractitemlevel
          - currency
          - customer
          - docusignaccount
          - document
          - documentversion
          - group
          - invite
          - invoice
          - invoiceConfiguration
          - organization
          - orgconfig
          - orgidentitytoken
          - payment
          - paymentMethod
          - paymentSchedule
          - paymentTerm
          - pricebook
          - pricebookentry
          - product
          - productlevel
          - productusage
          - proposal
          - proposalapprovalrule
          - proposalevent
          - proposalitem
          - proposaliteminterval
          - proposalitemlevel
          - proposaloption
          - refund
          - renewalconfiguration
          - signature
          - signingdocument
          - transfer
          - transferevent
          - unit
          - user
        paidAmountFormatted:
          type: string
        amountFormatted:
          type: string
        deleted:
          type: boolean
    SyncEvent:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
        referenceType:
          type: string
          enum:
          - account
          - apiwebhook
          - apitoken
          - approvalgroup
          - attachmentconfig
          - authidentity
          - billingschedule
          - companyInfo
          - connectorSyncEvent
          - contact
          - contentTemplate
          - contract
          - contractitem
          - contractitemlevel
          - currency
          - customer
          - docusignaccount
          - document
          - documentversion
          - group
          - invite
          - invoice
          - invoiceConfiguration
          - organization
          - orgconfig
          - orgidentitytoken
          - payment
          - paymentMethod
          - paymentSchedule
          - paymentTerm
          - pricebook
          - pricebookentry
          - product
          - productlevel
          - productusage
          - proposal
          - proposalapprovalrule
          - proposalevent
          - proposalitem
          - proposaliteminterval
          - proposalitemlevel
          - proposaloption
          - refund
          - renewalconfiguration
          - signature
          - signingdocument
          - transfer
          - transferevent
          - unit
          - user
        referenceId:
          type: string
          format: uuid
        direction:
          type: string
          enum:
          - to_cacheflow
          - from_cacheflow
        eventType:
          type: string
          enum:
          - auth
          - created
          - updated
          - deleted
        action:
          type: string
          enum:
          - create
          - update
          - delete
          - upsert
          - noop
        externalSource:
          $ref: '#/components/schemas/ExternalSource'
        status:
          type: string
          enum:
          - success
          - error
        error:
          type: string
        source:
          type: string
          deprecated: true
          enum:
          - manual
          - close
          - plaid
          - stripe
          - hubspot
          - salesforce
          - avalara
          - quickbooks
          - profitwell
          - netsuite
          - google
          - warmly
          - zapier
          - cacheflow_checkout
        externalId:
          type: string
          deprecated: true
        externalIdLink:
          type: string
          deprecated: true
    ActivityDetails:
      title: ActivityDetails
      type: object
      properties:
        message:
          type: string
        type:
          type: string
          enum:
          - base
          - transaction
          - notification
          - integration
          - field_changes
      discriminator:
        propertyName: type
        mapping:
          transaction: '#/components/schemas/TransactionActivityDetails'
          integration: '#/components/schemas/SyncActivityDetails'
          field_changes: '#/components/schemas/FieldChangeActivityDetails'
          notification: '#/components/schemas/NotificationActivityDetails'
    CreateRefundRequest:
      required:
      - amount
      - processDate
      - transferId
      type: object
      properties:
        processDate:
          type: string
          format: date
        amount:
          type: integer
          format: int64
        transferId:
          type: string
          format: uuid
        note:
          maxLength: 255
          minLength: 0
          type: string
    Contact:
      required:
      - createdAt
      - customerReference
      - deleted
      - email
      - id
      - 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'
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        role:
          type: string
        deleted:
          type: boolean
        customerReference:
          $ref: '#/components/schemas/ObjectReference'
        referenceType:
          type: string
          enum:
          - account
          - apiwebhook
          - apitoken
          - approvalgroup
          - attachmentconfig
          - authidentity
          - billingschedule
          - companyInfo
          - connectorSyncEvent
          - contact
          - contentTemplate
          - contract
          - contractitem
          - contractitemlevel
          - currency
          - customer
          - docusignaccount
          - document
          - documentversion
          - group
          - invite
          - invoice
          - invoiceConfiguration
          - organization
          - orgconfig
          - orgidentitytoken
          - payment
          - paymentMethod
          - paymentSchedule
          - paymentTerm
          - pricebook
          - pricebookentry
          - product
          - productlevel
          - productusage
          - proposal
          - proposalapprovalrule
          - proposalevent
          - proposalitem
          - proposaliteminterval
          - proposalitemlevel
          - proposaloption
          - refund
          - renewalconfiguration
          - signature
          - signingdocument
          - transfer
          - transferevent
          - unit
          - user
    PaymentMethod:
      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
        internalName:
          type: string
        description:
          type: string
        enabled:
          type: boolean
        configured:
          type: boolean
        managed:
          type: boolean
        billingPeriods:
          type: array
          items:
            type: string
            enum:
            - month
            - quarter
            - halfyear
            - year
        account:
          $ref: '#/components/schemas/Account'
        accountId:
          type: string
          format: uuid
        paymentType:
          type: string
          enum:
          - ach
          - cc
          - check
          - custom
          - direct_debit
          - wire
          - external
          - manual
        customText:
          type: string
        configuration:
          type: object
          additionalProperties:
            type: object
        processor:
          type: string
          enum:
          - plaid
          - stripe
          - manual
        activePaymentMethod:
          type: boolean
        referenceType:
          type: string
          enum:
          - account
          - apiwebhook
          - apitoken
          - approvalgroup
          - attachmentconfig
          - authidentity
          - billingschedule
          - companyInfo
          - connectorSyncEvent
          - contact
          - contentTemplate
          - contract
          - contractitem
          - contractitemlevel
          - currency
          - customer
          - docusignaccount
          - document
          - documentversion
          - group
          - invite
          - invoice
          - invoiceConfiguration
          - organization
          - orgconfig
          - orgidentitytoken
          - payment
          - paymentMethod
          - paymentSchedule
          - paymentTerm
          - pricebook
          - pricebookentry
          - product
          - productlevel
          - productusage
          - proposal
          - proposalapprovalrule
          - proposalevent
          - proposalitem
          - proposaliteminterval
          - proposalitemlevel
          - proposaloption
          - refund
          - renewalconfiguration
          - signature
          - signingdocument
          - transfer
          - transferevent
          - unit
          - user
        deleted:
          type: boolean
    Account:
      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
        address:
          $ref: '#/components/schemas/Address'
        institutionName:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
          - depository
          - credit
          - manual
          - external
        subtype:
          type: string
        mask:
          type: string
        legalName:
          type: string
        currency:
          type: string
        ownerType:
          type: string
        routingNumber:
          type: string
        accountNumber:
          type: string
        wireNumber:
          type: string
        expMonth:
          type: integer
          format: int32
        expYear:
          type: integer
          format: int32
        cvv:
          type: integer
          format: int32
        bic:
          type: string
        iban:
          type: string
        sortCode:
          type: string
        institutionNumber:
          type: string
        transitNumber:
          type: string
        verificationLink:
          type: string
        mandateId:
          type: string