openapi: 3.0.0
info:
  description: APIs for interacting with Cadana Embedded Consumer Wallets
  version: 1.0.0
  title: Embedded Consumer Wallets Balances Invoices API
  termsOfService: https://cadanapay.com/terms-and-conditions
  contact:
    email: api@cadanapay.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.cadanapay.com
  description: Prod Server
- url: https://dev-api.cadanapay.com
  description: Dev Server
security:
- Authorization: []
tags:
- name: Invoices
  description: APIs for interacting with invoices
paths:
  /v1/invoices:
    get:
      summary: List Invoices
      description: List invoices for your business. Optionally filter by person, user, source, status, type, or invoice date range. Filters can be combined; all are optional.
      operationId: listInvoices
      tags:
      - Invoices
      parameters:
      - $ref: '#/components/parameters/XMultiTenantKey'
      - name: personId
        in: query
        required: false
        description: Only include invoices for this person (e.g. the contractor the invoice pays). Matches the `personId` field on the invoice.
        schema:
          type: string
          format: uuid
      - name: userId
        in: query
        required: false
        description: Only include invoices belonging to this user
        schema:
          type: string
          format: uuid
      - name: source
        in: query
        required: false
        description: Filter by invoice origin, e.g. only contractor-submitted invoices (CONTRACTOR_SUBMITTED) or invoices auto-created from payroll (PAYROLL)
        schema:
          type: string
          enum:
          - SYSTEM
          - USER
          - REIMBURSEMENT
          - PAYROLL
          - CONTRACTOR_SUBMITTED
      - name: status
        in: query
        required: false
        description: Filter by invoice status (case-insensitive), e.g. Pending, Processing, Paid, Partially Paid, Overdue, Cancelled
        schema:
          type: string
      - name: type
        in: query
        required: false
        description: Filter by invoice type
        schema:
          type: string
          enum:
          - MANUAL
          - PAYROLL
          - CONTRACTOR
      - name: startDate
        in: query
        required: false
        description: Only include invoices with an invoice date on or after this date
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        required: false
        description: Only include invoices with an invoice date on or before this date
        schema:
          type: string
          format: date
      - name: limit
        in: query
        required: false
        description: Maximum number of invoices to return per page (default 20)
        schema:
          type: integer
          default: 20
      - name: cursor
        in: query
        required: false
        description: Opaque pagination cursor from the previous page's `node.next`. Omit to start from the first page.
        schema:
          type: string
      responses:
        '200':
          description: A list of invoices
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        status:
                          type: string
                          description: Invoice status
                        source:
                          type: string
                          enum:
                          - SYSTEM
                          - USER
                          - REIMBURSEMENT
                          - PAYROLL
                          - CONTRACTOR_SUBMITTED
                          description: Origin of the invoice
                        type:
                          type: string
                          enum:
                          - MANUAL
                          - PAYROLL
                          - CONTRACTOR
                          description: Invoice type
                        invoiceNumber:
                          type: string
                          description: Human-readable invoice number
                        from:
                          type: string
                          description: Name of the invoice issuer
                        billTo:
                          type: string
                          description: Name of the billed party
                        personId:
                          type: string
                          format: uuid
                          description: The person the invoice is for (e.g. the contractor being paid), when applicable
                        userId:
                          type: string
                          format: uuid
                          description: The user the invoice belongs to, when applicable
                        date:
                          type: string
                          format: date
                          description: Invoice date
                        datePayable:
                          type: string
                          format: date
                          description: Date the invoice is payable
                        subtotalAmount:
                          type: array
                          description: Subtotal per currency
                          items:
                            type: object
                            properties:
                              value:
                                type: string
                                description: Decimal amount as a string
                              currency:
                                type: string
                        totalAmount:
                          type: array
                          description: Total per currency
                          items:
                            type: object
                            properties:
                              value:
                                type: string
                                description: Decimal amount as a string
                              currency:
                                type: string
                  node:
                    type: object
                    description: Pagination cursors
                    properties:
                      previous:
                        type: string
                        nullable: true
                        description: Cursor this page started from; null on the first page
                      next:
                        type: string
                        nullable: true
                        description: Cursor for the next page; null when there are no more results
              example:
                data:
                - id: 0f6c2f8a-3d9b-4c57-9a41-8f2f6f7f1c33
                  status: Pending
                  source: PAYROLL
                  type: CONTRACTOR
                  invoiceNumber: '1764332528'
                  from: Ada Lovelace
                  billTo: Globex LLC
                  personId: 9d2f7a44-1be3-4e28-8d40-63f19a7d5b8e
                  userId: b58725e6-fabc-4a1a-9e5f-31efdbdbc45f
                  date: '2025-11-28'
                  datePayable: '2025-12-28'
                  subtotalAmount:
                  - value: '800.00'
                    currency: USD
                  totalAmount:
                  - value: '800.00'
                    currency: USD
                - id: ca51f42c-0adc-4a77-8dd1-a03dd4fb955f
                  status: Paid
                  source: SYSTEM
                  type: MANUAL
                  invoiceNumber: '1764332529'
                  from: Acme Inc
                  billTo: Globex LLC
                  date: '2025-11-28'
                  datePayable: '2025-12-28'
                  subtotalAmount:
                  - value: '800.00'
                    currency: USD
                  totalAmount:
                  - value: '880.00'
                    currency: USD
                node:
                  next: eyJ0ZW5hbnRLZXkiOnsiUyI6InRibDI4MTUzMjA4In0sInNvcnRLZXkiOnsiUyI6ImNhNTFmNDJjIn19
        5XX:
          $ref: '#/components/responses/InternalError'
      security:
      - Authorization: []
  /v1/invoices/{invoiceId}:
    get:
      summary: Get Invoice
      description: Get invoice details
      operationId: getInvoice
      tags:
      - Invoices
      parameters:
      - $ref: '#/components/parameters/invoiceId'
      - $ref: '#/components/parameters/XMultiTenantKey'
      responses:
        '200':
          $ref: '#/components/responses/GetInvoiceResponse'
        '404':
          $ref: '#/components/responses/NotFoundError'
        5XX:
          $ref: '#/components/responses/InternalError'
      security:
      - Authorization: []
  /v1/invoices/{invoiceId}/url:
    get:
      summary: Get Invoice URL
      description: Get a short-lived URL for the invoice PDF
      operationId: getInvoiceUrl
      tags:
      - Invoices
      parameters:
      - $ref: '#/components/parameters/invoiceId'
      - $ref: '#/components/parameters/XMultiTenantKey'
      responses:
        '200':
          $ref: '#/components/responses/GetInvoiceUrlResponse'
        '404':
          $ref: '#/components/responses/NotFoundError'
        5XX:
          $ref: '#/components/responses/InternalError'
      security:
      - Authorization: []
  /v1/invoices/{invoiceId}/review:
    post:
      summary: Review Invoice
      description: Approve or reject a contractor self-submitted invoice. Only invoices with a `source` of `CONTRACTOR_SUBMITTED` in `pending` status can be reviewed; any other invoice returns 400.
      operationId: reviewInvoice
      tags:
      - Invoices
      parameters:
      - $ref: '#/components/parameters/invoiceId'
      - $ref: '#/components/parameters/XMultiTenantKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - action
              properties:
                action:
                  type: string
                  enum:
                  - approve
                  - reject
                  description: Whether to approve or reject the invoice
                reason:
                  type: string
                  description: Reason for the decision. Required when action is reject.
      responses:
        '204':
          description: Invoice reviewed
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        5XX:
          $ref: '#/components/responses/InternalError'
      security:
      - Authorization: []
  /v1/invoices/{invoiceId}/cancel:
    post:
      summary: Cancel Invoice
      description: Cancel an invoice. The invoice is voided and can no longer be paid or reviewed.
      operationId: cancelInvoice
      tags:
      - Invoices
      parameters:
      - $ref: '#/components/parameters/invoiceId'
      - $ref: '#/components/parameters/XMultiTenantKey'
      responses:
        '204':
          description: Invoice cancelled
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        5XX:
          $ref: '#/components/responses/InternalError'
      security:
      - Authorization: []
components:
  responses:
    InternalError:
      description: Internal error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalError'
    GetInvoiceUrlResponse:
      description: get invoice url response
      content:
        application/json:
          schema:
            type: object
            properties:
              fileUrl:
                type: string
                format: uri
                description: Short-lived URL for the invoice PDF
                example: https://cadana.com/file/124
              expiresAt:
                type: integer
                format: int64
                description: Unix timestamp when the URL expires
                example: 1710590400
          examples:
            invoiceUrlResponse:
              $ref: '#/components/examples/invoiceUrlResponse'
    NotFoundError:
      description: Requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    GetInvoiceResponse:
      description: get invoice response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/invoice'
          examples:
            invoiceResponse:
              $ref: '#/components/examples/invoiceResponse'
    BadRequestError:
      description: Bad input provided by client
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestError'
  schemas:
    phoneNumber:
      type: object
      description: Person's phone number
      properties:
        countryCode:
          type: string
          example: '1'
        number:
          type: string
          example: '2345678901'
    uuid:
      type: string
      format: uuid
      example: 8ef9a712-cdae-4110-b1ea-9ba95abbee6e
    NotFoundError:
      description: Not Found
      allOf:
      - $ref: '#/components/schemas/Error'
      example:
        code: resource_not_found
        message: Requested resource could not be found.
    InternalError:
      description: Internal server error
      allOf:
      - $ref: '#/components/schemas/Error'
      example:
        code: internal_error
        message: An unexpected error occurred. Please try again later.
    BadRequestError:
      description: Bad input provided by client
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        properties:
          params:
            description: A map for meta data around the error that occurred
            type: object
      example:
        code: invalid_request_body
        message: The request body provided is not valid
        params:
          field: Value is invalid.
    amount:
      type: object
      required:
      - amount
      - currency
      properties:
        amount:
          type: integer
          description: value in lowest denomination
          example: 10000
        currency:
          type: string
          description: currency
          example: USD
    invoiceParty:
      type: object
      description: Details of a party on an invoice (issuer or recipient)
      properties:
        name:
          type: string
          example: Example Company LLC
        address:
          type: string
          example: 123 Main Street, Suite 100, New York City, NY 10001
        email:
          type: string
          format: email
          example: billing@example.com
        phoneNumber:
          $ref: '#/components/schemas/phoneNumber'
    invoiceLineItem:
      type: object
      description: A line item on an invoice
      properties:
        personId:
          $ref: '#/components/schemas/uuid'
          description: Person ID (for payroll items)
        description:
          type: string
          example: John Doe
        category:
          type: string
          description: Line-item category. Direct-employment payrolls produce `NET_PAYROLL` plus fee items; EOR payrolls produce `GROSS_PAYROLL` and `EMPLOYER_CONTRIBUTION`.
          enum:
          - NET_PAYROLL
          - GROSS_PAYROLL
          - EMPLOYER_CONTRIBUTION
          - PAYMENT_PROCESSING_FEE
          - CONTRACTOR_FEE
          - EMPLOYEE_FEE
          example: NET_PAYROLL
        amount:
          $ref: '#/components/schemas/amount'
          description: Unit amount in base currency
        originalAmount:
          $ref: '#/components/schemas/amount'
          description: Amount in original currency (if different from base)
        fxRate:
          type: number
          format: float
          description: Exchange rate applied (if currency conversion occurred)
          example: 58.21
        quantity:
          type: integer
          example: 1
        total:
          $ref: '#/components/schemas/amount'
          description: Total amount in base currency
    invoice:
      type: object
      description: An invoice document
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        status:
          type: string
          enum:
          - pending
          - approved
          - rejected
          - partially paid
          - paid
          - overdue
          - cancelled
          example: paid
        source:
          type: string
          enum:
          - SYSTEM
          - USER
          - REIMBURSEMENT
          - PAYROLL
          - CONTRACTOR_SUBMITTED
          description: Origin of the invoice. Only invoices with source CONTRACTOR_SUBMITTED are reviewable via the review endpoint.
          example: CONTRACTOR_SUBMITTED
        invoiceNumber:
          type: string
          example: '1764332528'
          description: Human-readable invoice number
        date:
          type: string
          format: date
          example: '2025-11-28'
          description: Invoice date
        dueDate:
          type: string
          format: date
          example: '2025-11-26'
          description: Payment due date
        from:
          $ref: '#/components/schemas/invoiceParty'
          description: Invoice issuer
        billTo:
          $ref: '#/components/schemas/invoiceParty'
          description: Invoice recipient
        items:
          type: array
          items:
            $ref: '#/components/schemas/invoiceLineItem'
        subtotal:
          $ref: '#/components/schemas/amount'
          description: Subtotal before any adjustments
        total:
          $ref: '#/components/schemas/amount'
          description: Total amount due
        baseCurrency:
          type: string
          example: USD
          description: Base currency for the invoice
        fxRates:
          type: object
          description: Exchange rates used in this invoice
          additionalProperties:
            type: number
            format: float
          example:
            USD-EUR: 0.863673
            USD-PHP: 58.208258
        purpose:
          type: string
          example: Payment Processing Fee
          description: Purpose of the invoice
        notes:
          type: string
          example: Payment for services rendered
          description: Additional notes
        createdTimestamp:
          type: integer
          format: int64
          example: 1764332530
          description: Unix timestamp when invoice was created
        lastUpdatedTimestamp:
          type: integer
          format: int64
          example: 1764339673
          description: Unix timestamp when invoice was last updated
    Error:
      type: object
      properties:
        code:
          description: A machine parsable error code
          type: string
          enum:
          - invalid_request_body
          - resource_not_found
          - forbidden
          - internal_error
        message:
          description: A human readable message describing the error
          type: string
  examples:
    invoiceUrlResponse:
      summary: Invoice URL Response Example
      value:
        fileUrl: https://cadana.com/file/124
        expiresAt: 1710590400
    invoiceResponse:
      summary: Invoice Response Example
      value:
        id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        status: paid
        invoiceNumber: INV-2024-001
        date: '2024-03-15'
        dueDate: '2024-03-30'
        from:
          name: Acme Corp
          address: 123 Business St, Suite 100, San Francisco, CA 94105
          email: billing@example.com
          phoneNumber:
            countryCode: '1'
            number: '4155551234'
        billTo:
          name: Example Corp
          address: 456 Innovation Ave, Austin, TX 78701
          email: accounts@example.com
          phoneNumber:
            countryCode: '1'
            number: '5125555678'
        items:
        - personId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
          description: John Doe - Consulting Services
          category: NET_PAYROLL
          amount:
            amount: 350000
            currency: USD
          quantity: 1
          total:
            amount: 350000
            currency: USD
        - personId: 8d7f5678-8536-41ef-a55c-f18ad2c01bf8
          description: Jane Smith - Development Work
          category: NET_PAYROLL
          originalAmount:
            amount: 150000
            currency: EUR
          amount:
            amount: 162500
            currency: USD
          fxRate: 1.0833
          quantity: 1
          total:
            amount: 162500
            currency: USD
        - description: International Transfer Fees
          category: PAYMENT_PROCESSING_FEE
          amount:
            amount: 2500
            currency: USD
          quantity: 1
          total:
            amount: 2500
            currency: USD
        - description: Service Fee
          category: CONTRACTOR_FEE
          amount:
            amount: 5000
            currency: USD
          quantity: 2
          total:
            amount: 10000
            currency: USD
        subtotal:
          amount: 525000
          currency: USD
        total:
          amount: 525000
          currency: USD
        baseCurrency: USD
        fxRates:
          USD-EUR: 0.92
          EUR-USD: 1.0833
        purpose: Professional Services
        notes: Payment for services rendered in March 2024
        createdTimestamp: 1710504000
        lastUpdatedTimestamp: 1710590400
  parameters:
    XMultiTenantKey:
      name: X-MultiTenantKey
      in: header
      required: false
      schema:
        type: string
      description: Required when using a Platform API token. The tenant key identifying which business to operate on.
    invoiceId:
      name: invoiceId
      in: path
      description: The unique identifier for the invoice
      required: true
      schema:
        type: string
        format: uuid
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      bearerFormat: API_SECRET_KEY
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true