openapi: 3.1.1
info:
  title: Upflow API
  contact:
    name: Upflow Support
    email: support@upflow.io
  version: ''
  description: |
    Upflow api documentation.

    ## Sandbox Environment

    You can develop and test your integration in our API sandbox:
    `https://api.sandbox.upflow.io/v1/`

    ## Reliability recommendations

    Make sure to implement API call retries with exponential backoff for the
    rare cases of API being down.

    ## Authentication

    All requests must include the `X-Api-Key` and `X-Api-Secret` authentication
    headers with each request. Project administrators can obtain these from the
    settings menu.

    ## Addressing Models using `externalId`

    All models contain an `externalId` field. You can use this field to store
    your own identifier in Upflow.

    If you opt for this type of integration, you can prefix ids with `external:`
    in order to lookup Upflow models using your identifier.

    Examples:

    - `GET https://api.upflow.io/v1/customers/12345` returns the customer with
    `id = 12345`

    - `GET https://api.upflow.io/v1/customers/external:12345` returns the
    customer with `externalId = 12345`

    ## Pagination

    List endpoints are compatible with both page-based and offset-based pagination.

    ---
    ## Additional Information

    - All amounts are stored as `Integer` and represent the lowest division of
    the currency (e.g., cents for US Dollars).

    - Currencies follow [ISO
    4217](https://www.iso.org/iso-4217-currency-codes.html) (e.g., EUR, USD,
    GBP).

    - The API is rate limited to 600 requests per minute.
servers:
  - url: https://api.upflow.io/v1
    description: Production server
  - url: https://api.sandbox.upflow.io/v1
    description: Sandbox server
tags:
  - name: Actions
    description: Manage actions.
  - name: Assigned Users
    description: Manage users assigned to customers (Account Managers).
  - name: Bank Accounts
    description: Manage bank accounts.
  - name: Contacts
    description: Manage customer contacts.
  - name: Credit Notes
    description: Manage credit notes.
  - name: Custom Fields
    description: Manage custom fields definitions.
  - name: Customers
    description: Manage customers. Handles `external ids` on `customer` level.
  - name: Dunning Plans
    description: Retrieve dunning plans (also known as workflows).
  - name: Invoices
    description: Manage invoices.
  - name: Notes
    description: Retrieve notes.
  - name: Operations
    description: Perform general operations like reconciliation.
  - name: Payments
    description: Manage payments.
  - name: Refunds
    description: Manage refunds.
  - name: Users
    description: Retrieve user information.
paths:
  /invoices:
    post:
      tags:
        - Invoices
      summary: Import Invoice
      description: |
        This endpoint can be used to create or update (if externalId already
        exists) an invoice.

        It cannot be used when using a native integration as invoices are only
        created by the native integration in that case.
      operationId: importInvoice
      requestBody:
        description: Invoice data to import.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InvoiceCommonAttribsNoPDF"
      responses:
        "201":
          description: Invoice Created or Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
      security:
        - ApiKey: []
          ApiSecret: []
    get:
      tags:
        - Invoices
      summary: List Invoices
      description: List invoices with optional filtering.
      operationId: listInvoices
      parameters:
        - $ref: "#/components/parameters/paginationOffset"
        - $ref: "#/components/parameters/paginationPage"
        - $ref: "#/components/parameters/paginationLimit"
        - name: customer.id
          in: query
          description: Filter invoices by Customer ID.
          required: false
          schema:
            type: string
            examples:
              - 00a70b35-2be3-4c43-aefb-397190134655
        - name: customer.externalId
          in: query
          description: Filter invoices by external Customer ID.
          required: false
          schema:
            type: string
            examples:
              - "134"
        - name: updatedAt
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/RangeQueryUpdateSpecs"
        - name: customId
          in: query
          description: Filter invoices by custom ID.
          required: false
          schema:
            type: string
            examples:
              - INV123
        - name: dunningPlanId
          in: query
          description: Filter invoices by dunning plan ID.
          required: false
          schema:
            type: string
            examples:
              - 35d440f2-aa53-4b22-84ba-0a4274e800e0
        - name: state
          in: query
          description: Filter invoices by state.
          required: false
          schema:
            $ref: "#/components/schemas/InvoiceStatus"
        - name: sortBy
          in: query
          description: Sort invoices by a specific column.
          required: false
          schema:
            type: string
            enum:
              - customId
              - updatedAt
            examples:
              - customId
              - updatedAt
        - name: sortOrder
          in: query
          description: Sort order.
          required: false
          schema:
            type: string
            enum:
              - DESC
              - ASC
            default: DESC
      responses:
        "200":
          description: Paginated list of invoices.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PaginationMetadata"
                  - type: object
                    required:
                      - invoices
                    properties:
                      invoices:
                        type: array
                        items:
                          $ref: "#/components/schemas/Invoice"
      security:
        - ApiKey: []
          ApiSecret: []
  /invoices/{invoiceId}:
    parameters:
      - name: invoiceId
        in: path
        description: The Invoice ID or `external:{externalId}`.
        required: true
        schema:
          type: string
        examples:
          default:
            value: 00a70b35-2be3-4c43-aefb-397190134655
    put:
      tags:
        - Invoices
      summary: Update Invoice
      description: This endpoint can be used to update an invoice dunning plan,
        promise to pay or user defined custom fields.
      operationId: updateInvoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InvoiceUpdateAttribs"
      responses:
        "200":
          description: Invoice Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
      security:
        - ApiKey: []
          ApiSecret: []
    get:
      tags:
        - Invoices
      summary: Get Invoice
      description: This endpoint can be used to retrieve a specific invoice by its ID.
      operationId: getInvoice
      responses:
        "200":
          description: Invoice details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
      security:
        - ApiKey: []
          ApiSecret: []
    delete:
      tags:
        - Invoices
      summary: Delete Invoice
      description: This endpoint can be used to delete a specific invoice by its ID.
      operationId: deleteInvoice
      responses:
        "204":
          description: Invoice deleted successfully.
      security:
        - ApiKey: []
          ApiSecret: []
  /invoices/{invoiceId}/pdf:
    parameters:
      - name: invoiceId
        in: path
        description: The Invoice ID or `external:{externalId}`.
        required: true
        schema:
          type: string
        examples:
          default:
            value: 00a70b35-2be3-4c43-aefb-397190134655
    post:
      tags:
        - Invoices
      summary: Upload Invoice PDF
      description:
        You can either send the PDF in a multipart/form-data request (i.e.
        a regular "file upload" in HTML) or a JSON request with the file encoded
        in base64.
      operationId: uploadInvoicePdf
      requestBody:
        description: PDF file content.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PDFImportAttr"
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: The PDF file to upload.
                  contentMediaType: application/octet-stream
              required:
                - file
      responses:
        "204":
          description: PDF uploaded successfully.
      security:
        - ApiKey: []
          ApiSecret: []
  /customers/{customerId}/invoices:
    parameters:
      - name: customerId
        in: path
        description: The Customer ID or `external:{externalId}`.
        required: true
        schema:
          type: string
    post:
      tags:
        - Invoices
      summary: Import Invoice (deprecated)
      deprecated: true
      description: Use POST /invoices instead.
      operationId: importInvoiceLegacy
      requestBody:
        description: Invoice data to import.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LegacyInvoiceCommonAttribsNoPDF"
      responses:
        "201":
          description: Invoice Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
      security:
        - ApiKey: []
          ApiSecret: []
  /customers:
    post:
      tags:
        - Customers
      summary: Import Customer
      description: |
        This endpoint can be used to create or update (if externalId already
        exists) a customer.

        This endpoint cannot be used when using a native integration as
        customers are only created by the native integration in that case.
      operationId: importCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/CustomerAttribs"
                - type: object
                  properties:
                    contacts:
                      deprecated: true
                      type: array
                      items:
                        $ref: "#/components/schemas/ContactAttribs"
                      description:
                        (Deprecated) Optional list of contacts to create alongside the
                        customer. This field is deprecated and will be removed in the
                        future, use the `POST /customers/{customer_id}/contacts`
                        endpoint instead.
      responses:
        "201":
          description: Customer Created or Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Customer"
      security:
        - ApiKey: []
          ApiSecret: []
    get:
      tags:
        - Customers
      summary: List Customers
      description: List customers with optional filtering.
      operationId: listCustomers
      parameters:
        - $ref: "#/components/parameters/paginationOffset"
        - $ref: "#/components/parameters/paginationPage"
        - $ref: "#/components/parameters/paginationLimit"
        - name: sortBy
          in: query
          description: Sort customers by a specific column.
          required: false
          schema:
            type: string
            enum:
              - balance
              - createdAt
            default: createdAt
            description: "Sort by column: `balance` or `createdAt`."
        - name: sortOrder
          in: query
          description: Sort order.
          required: false
          schema:
            type: string
            enum:
              - DESC
              - ASC
            default: DESC
        - name: balance.gte
          in: query
          description:
            Return customers having a balance greater than or equal to this
            value (in cents).
          required: false
          schema:
            type: integer
            examples:
              - 20000
        - name: balance.lte
          in: query
          description:
            Return customers having a balance lower than or equal to this value
            (in cents).
          required: false
          schema:
            type: integer
            examples:
              - 20000
        - name: amountDue.eq
          in: query
          description: Return customers where amountDue is equal to this value (in cents).
          required: false
          schema:
            type: integer
            examples:
              - 0
        - name: updatedAt
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/RangeQueryUpdateSpecs"
        - name: dunningPlanId
          in: query
          description: Filter customers by dunning plan ID.
          required: false
          schema:
            type: string
            examples:
              - c2b568ac-ef97-4e3c-968b-2b39af2cdcea
      responses:
        "200":
          description: Paginated list of customers.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PaginationMetadata"
                  - type: object
                    required:
                      - customers
                    properties:
                      customers:
                        type: array
                        items:
                          $ref: "#/components/schemas/Customer"
      security:
        - ApiKey: []
          ApiSecret: []
  /customers/{customerId}:
    parameters:
      - name: customerId
        in: path
        description: The Customer ID or `external:{externalId}`.
        required: true
        schema:
          type: string
        examples:
          default:
            value: 00a70b35-2be3-4c43-aefb-397190134655
    put:
      tags:
        - Customers
      summary: Update Customer
      description: This endpoint can be used to update an existing customer.
      operationId: updateCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomerAttribs"
      responses:
        "200":
          description:
            "Customer Updated Successfully (Note: Apiary doc says 201, but PUT
            usually returns 200 on success)"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Customer"
      security:
        - ApiKey: []
          ApiSecret: []
    get:
      tags:
        - Customers
      summary: Get Customer
      description: This endpoint can be used to retrieve a specific customer by its ID.
      operationId: getCustomer
      responses:
        "200":
          description: Customer details.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Customer"
                  - type: object
                    properties:
                      contacts:
                        deprecated: true
                        type: array
                        items:
                          $ref: "#/components/schemas/Contact"
                        description:
                          (Deprecated) List of contacts associated with the customer.
                          This field is deprecated and will be removed in the future,
                          use the `GET /customers/{customer_id}/contacts` endpoint
                          instead.
      security:
        - ApiKey: []
          ApiSecret: []
    delete:
      tags:
        - Customers
      summary: Delete Customer
      description: This endpoint can be used to delete a specific customer by its ID.
      operationId: deleteCustomer
      responses:
        "204":
          description: Customer deleted successfully.
      security:
        - ApiKey: []
          ApiSecret: []
  /customers/{customerId}/portal:
    parameters:
      - name: customerId
        in: path
        description: The Customer ID or `external:{externalId}`.
        required: true
        schema:
          type: string
        examples:
          default:
            value: 00a70b35-2be3-4c43-aefb-397190134655
    post:
      tags:
        - Customers
      summary: Create Portal Url
      description: |
        This endpoint is used to generate a portal URL for a customer. You can
        link this URL in your app, or embed it in an iframe to allow your users
        to access the customer portal from your app. To embed it in an iframe,
        you must specify the `frameAncestors` attribute in the request.

        The call to retrieve the portal URL must strictly be made from the
        backend (not the frontend) as it utilises the client’s API secret.
      operationId: createCustomerPortalUrl
      requestBody:
        description: Options for generating the portal URL.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  type: string
                  format: email
                  description:
                    An email identifying the user who is using the generated URL and
                    the token.
                  examples:
                    - john@customer.com
                frameAncestors:
                  type: string
                  description:
                    Space-separated fully qualified domain names which are authorized
                    to embed the portal in an iframe.
                  examples:
                    - extranet.merchant.com intranet.merchant.com
                expiresIn:
                  type: integer
                  format: int32
                  description:
                    Expressed in seconds. Time span during which the token is valid.
                    Default is 86400 (1 day).
                  default: 86400
                  examples:
                    - 86400
            examples:
              embed_24h:
                summary: Embedding the customer portal, valid for 24 hours
                value:
                  user: john@customer.com
                  frameAncestors: extranet.merchant.com intranet.merchant.com
                  expiresIn: 86400
      responses:
        "200":
          description: Portal URL generated successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                  - url
                properties:
                  url:
                    type: string
                    format: uri
                    description: The URL for the Customer Summary Page including the access token.
                    examples:
                      - https://app.upflow.com/customers/00a70b35-2be3-4c43-aefb-397190134655?token=xxx
      security:
        - ApiKey: []
          ApiSecret: []
  /customers/{customer_id}/contacts:
    parameters:
      - name: customer_id
        in: path
        description: The Customer ID or `external:{externalId}`.
        required: true
        schema:
          type: string
        examples:
          default:
            value: 00a70b35-2be3-4c43-aefb-397190134655
    post:
      tags:
        - Contacts
      summary: Create Customer Contact
      description:
        This endpoint can be used to create a new contact for a specific
        customer.
      operationId: createCustomerContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContactAttribs"
      responses:
        "201":
          description: Contact Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Contact"
      security:
        - ApiKey: []
          ApiSecret: []
    get:
      tags:
        - Contacts
      summary: List Customer Contacts
      description: List contacts for a specific customer.
      operationId: listCustomerContacts
      parameters:
        - $ref: "#/components/parameters/paginationOffset"
        - $ref: "#/components/parameters/paginationPage"
        - $ref: "#/components/parameters/paginationLimit"
      responses:
        "200":
          description: Paginated list of customer contacts.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PaginationMetadata"
                  - type: object
                    required:
                      - contacts
                    properties:
                      contacts:
                        type: array
                        items:
                          $ref: "#/components/schemas/Contact"
      security:
        - ApiKey: []
          ApiSecret: []
  /customers/{customer_id}/contacts/{id}:
    parameters:
      - name: customer_id
        in: path
        description: The Customer ID or `external:{externalId}`.
        required: true
        schema:
          type: string
        examples:
          default:
            value: 00a70b35-2be3-4c43-aefb-397190134655
      - name: id
        in: path
        description: The Contact ID or `external:{externalId}`.
        required: true
        schema:
          type: string
        examples:
          default:
            value: 00a70b35-2be3-4c43-aefb-397190134611
      - name: source
        in: query
        description:
          Source system of the contact to update. Required if multiple
          contacts with the same ID exist for different sources.
        required: false
        schema:
          type: string
        examples:
          default:
            value: crm
    put:
      tags:
        - Contacts
      summary: Update Customer Contact
      description: This endpoint can be used to update an existing customer contact.
      operationId: updateCustomerContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContactAttribs"
      parameters:
        - $ref: "#/components/parameters/source"
      responses:
        "200":
          description: Contact Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Contact"
      security:
        - ApiKey: []
          ApiSecret: []
    get:
      tags:
        - Contacts
      summary: Get Customer Contact
      description: This endpoint can be used to retrieve a specific customer contact by its ID.
      operationId: getCustomerContact
      parameters:
        - $ref: "#/components/parameters/source"
      responses:
        "200":
          description: Contact details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Contact"
      security:
        - ApiKey: []
          ApiSecret: []
    delete:
      tags:
        - Contacts
      summary: Delete Customer Contact
      description: This endpoint can be used to delete a specific customer contact by its ID.
      operationId: deleteCustomerContact
      parameters:
        - $ref: "#/components/parameters/source"
      responses:
        "204":
          description: Contact deleted successfully.
      security:
        - ApiKey: []
          ApiSecret: []
  /customers/{customerId}/account-managers:
    parameters:
      - name: customerId
        in: path
        description: The Customer ID or `external:{externalId}`.
        required: true
        schema:
          type: string
        examples:
          default:
            value: 00a70b35-2be3-4c43-aefb-397190134655
    post:
      tags:
        - Assigned Users
      summary: Update Customer Assigned User List
      description:
        This endpoint can be used to update the list of assigned users
        for a specific customer.
      operationId: updateCustomerAssignedUsers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - userIds
              properties:
                userIds:
                  type: array
                  description: List of user IDs to assign to the customer.
                  items:
                    type: string
                    format: uuid
                  examples:
                    - - 00a70b35-2be3-4c43-aefb-397190134655
      responses:
        "200":
          description: Assigned user list updated.
          content:
            application/json:
              schema:
                type: object
                required:
                  - total
                  - items
                properties:
                  total:
                    type: integer
                    format: int32
                    description: Total number of assigned users for the customer.
                    examples:
                      - 1
                  items:
                    type: array
                    description: Assigned user items.
                    items:
                      $ref: "#/components/schemas/AccountManager"
      security:
        - ApiKey: []
          ApiSecret: []
    get:
      tags:
        - Assigned Users
      summary: List Customer Assigned Users
      description: This endpoint can be used to list assigned users for a specific customer.
      operationId: listCustomerAssignedUsers
      responses:
        "200":
          description: List of assigned users for the customer.
          content:
            application/json:
              schema:
                type: object
                required:
                  - total
                  - items
                properties:
                  total:
                    type: integer
                    format: int32
                    description: Total number of assigned users for the customer.
                    examples:
                      - 1
                  items:
                    type: array
                    description: Assigned user items.
                    items:
                      $ref: "#/components/schemas/AccountManager"
      security:
        - ApiKey: []
          ApiSecret: []
  /payments:
    post:
      tags:
        - Payments
      summary: Import payment
      description: |
        This endpoint can be used to create or update (if externalId already
        exists) a payment.

        It cannot be used when using a native integration as payments are only
        created by the native integration in that case.
      operationId: importPayment
      requestBody:
        description: Payment data to import.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentCreation"
      responses:
        "201":
          description: Payment Created or Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payment"
      security:
        - ApiKey: []
          ApiSecret: []
    get:
      tags:
        - Payments
      summary: List Payments
      description: List payments with optional filtering.
      operationId: listPayments
      parameters:
        - $ref: "#/components/parameters/paginationOffset"
        - $ref: "#/components/parameters/paginationPage"
        - $ref: "#/components/parameters/paginationLimit"
        - name: sortBy
          in: query
          description: Sort payments by a specific column.
          required: false
          schema:
            type: string
            enum:
              - updatedAt
              - validatedAt
              - createdAt
            default: createdAt
        - name: sortOrder
          in: query
          description: Sort order.
          required: false
          schema:
            type: string
            enum:
              - DESC
              - ASC
            default: DESC
        - name: updatedAt
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/RangeQueryUpdateSpecs"
        - name: validatedAt
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/RangeQueryValidationSpecs"
        - name: amountLinked
          in: query
          description:
            Return payments where allocated amount is equal to this value (in
            cents).
          required: false
          schema:
            type: integer
            examples:
              - 0
        - name: amountLinked.gt
          in: query
          description:
            Return payments where allocated amount is greater than this value
            (in cents).
          required: false
          schema:
            type: integer
            examples:
              - 0
        - name: amountLinked.gte
          in: query
          description:
            Return payments where allocated amount is greater than or equal to
            this value (in cents).
          required: false
          schema:
            type: integer
            examples:
              - 0
        - name: amountLinked.lt
          in: query
          description:
            Return payments where allocated amount is lower than this value (in
            cents).
          required: false
          schema:
            type: integer
            examples:
              - 100000
        - name: amountLinked.lte
          in: query
          description:
            Return payments where allocated amount is lower than or equal to
            this value (in cents).
          required: false
          schema:
            type: integer
            examples:
              - 100000
        - name: amount
          in: query
          description: Return payments where amount is equal to this value (in cents).
          required: false
          schema:
            type: integer
            examples:
              - 300000
        - name: amount.gt
          in: query
          description: Return payments where amount is greater than this value (in cents).
          required: false
          schema:
            type: integer
            examples:
              - 300000
        - name: amount.gte
          in: query
          description:
            Return payments where amount is greater than or equal to this value
            (in cents).
          required: false
          schema:
            type: integer
            examples:
              - 300000
        - name: amount.lt
          in: query
          description: Return payments where amount is lower than this value (in cents).
          required: false
          schema:
            type: integer
            examples:
              - 300000
        - name: amount.lte
          in: query
          description:
            Return payments where amount is lower than or equal to this value
            (in cents).
          required: false
          schema:
            type: integer
            examples:
              - 300000
        - name: customer.id
          in: query
          description: Filter payments by Customer ID.
          required: false
          schema:
            type: string
            examples:
              - 00a70b35-2be3-4c43-aefb-397190134655
        - name: customer.externalId
          in: query
          description: Filter payments by external Customer ID.
          required: false
          schema:
            type: string
            examples:
              - "134"
        - name: modifiedAt
          in: query
          required: false
          deprecated: true
          schema:
            $ref: "#/components/schemas/RangeQueryModificationSpecs"
      responses:
        "200":
          description: Paginated list of payments.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentsListResponse"
      security:
        - ApiKey: []
          ApiSecret: []
  /payments/{paymentId}:
    parameters:
      - name: paymentId
        in: path
        description: The Payment ID or `external:{externalId}`.
        required: true
        schema:
          type: string
        examples:
          default:
            value: 00a70b35-2be3-4c43-aefb-397190134655
    get:
      tags:
        - Payments
      summary: Get Payment
      description: This endpoint can be used to get details of a specific payment by its ID.
      operationId: getPayment
      responses:
        "200":
          description: Payment details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payment"
      security:
        - ApiKey: []
          ApiSecret: []
    delete:
      tags:
        - Payments
      summary: Delete Payment
      description: This endpoint can be used to delete a specific payment by its ID.
      operationId: deletePayment
      responses:
        "204":
          description: Payment deleted successfully.
      security:
        - ApiKey: []
          ApiSecret: []
  /credit_notes:
    post:
      tags:
        - Credit Notes
      summary: Import credit note
      description: |
        This endpoint can be used to create or update (if externalId already
        exists) a credit note.

        It cannot be used when using a native integration as credit notes are
        only created by the native integration in that case.
      operationId: importCreditNote
      requestBody:
        description: Credit note data to import.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreditNoteCreation"
      responses:
        "201":
          description: Credit Note Created or Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreditNote"
      security:
        - ApiKey: []
          ApiSecret: []
    get:
      tags:
        - Credit Notes
      summary: List credit notes
      description: List credit notes with optional filtering.
      operationId: listCreditNotes
      parameters:
        - $ref: "#/components/parameters/paginationOffset"
        - $ref: "#/components/parameters/paginationPage"
        - $ref: "#/components/parameters/paginationLimit"
        - name: customer.id
          in: query
          description: Filter credit notes by Customer ID.
          required: false
          schema:
            type: string
            examples:
              - 00a70b35-2be3-4c43-aefb-397190134655
        - name: customer.externalId
          in: query
          description: Filter credit notes by external Customer ID.
          required: false
          schema:
            type: string
            examples:
              - "134"
        - name: updatedAt
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/RangeQueryUpdateSpecs"
        - name: customId
          in: query
          description: Filter credit notes by custom ID.
          required: false
          schema:
            type: string
            examples:
              - CN123
      responses:
        "200":
          description: Paginated list of credit notes.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreditNotesListResponse"
      security:
        - ApiKey: []
          ApiSecret: []
  /credit_notes/{creditNoteId}:
    parameters:
      - name: creditNoteId
        in: path
        description: The Credit Note ID or `external:{externalId}`.
        required: true
        schema:
          type: string
        examples:
          default:
            value: 00a70b35-2be3-4c43-aefb-397190134655
    get:
      tags:
        - Credit Notes
      summary: Get credit note
      description: This endpoint can be Get details of a specific credit note by its ID.
      operationId: getCreditNote
      responses:
        "200":
          description: Credit note details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreditNote"
      security:
        - ApiKey: []
          ApiSecret: []
    delete:
      tags:
        - Credit Notes
      summary: Delete Credit Note
      description: This endpoint can be used to delete a specific credit note by its ID.
      operationId: deleteCreditNote
      responses:
        "204":
          description: Credit Note deleted successfully.
      security:
        - ApiKey: []
          ApiSecret: []
  /credit_notes/{creditNoteId}/pdf:
    parameters:
      - name: creditNoteId
        in: path
        description: The Credit Note ID or `external:{externalId}`.
        required: true
        schema:
          type: string
        examples:
          default:
            value: 00a70b35-2be3-4c43-aefb-397190134655
    post:
      tags:
        - Credit Notes
      summary: Upload Credit Note PDF
      description:
        You can either send the PDF in a multipart/form-data request (ie. a
        regular "file upload" in HTML) or a JSON request with the file encoded
        in base64.
      operationId: uploadCreditNotePdf
      requestBody:
        description: PDF file content.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PDFImportAttr"
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: The PDF file to upload.
                  contentMediaType: application/octet-stream
              required:
                - file
      responses:
        "204":
          description: PDF uploaded successfully.
      security:
        - ApiKey: []
          ApiSecret: []
  /users:
    get:
      tags:
        - Users
      summary: List Users
      description: This endpoint can be used to list users with optional filtering.
      operationId: listUsers
      responses:
        "200":
          description: List of users.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserListResponse"
      security:
        - ApiKey: []
          ApiSecret: []
  /bank_accounts:
    get:
      tags:
        - Bank Accounts
      summary: List BankAccounts
      description: List bank accounts with optional filtering.
      operationId: listBankAccounts
      parameters:
        - $ref: "#/components/parameters/paginationOffset"
        - $ref: "#/components/parameters/paginationPage"
        - $ref: "#/components/parameters/paginationLimit"
      responses:
        "200":
          description: Paginated list of bank accounts.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PaginationMetadata"
                  - type: object
                    required:
                      - items
                    properties:
                      items:
                        type: array
                        items:
                          $ref: "#/components/schemas/BankAccount"
      security:
        - ApiKey: []
          ApiSecret: []
  /refunds:
    post:
      tags:
        - Refunds
      summary: Import Refund
      description: |
        This endpoint can be used to create or update (if externalId already
        exists) a refund.

        It cannot be used when using a native integration as refunds are only
        created by the native integration in that case.
      operationId: importRefund
      requestBody:
        description: Refund data to import.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RefundCreation"
      responses:
        "200":
          description:
            "Refund Created or Updated (Note: Apiary doc says 200, usually POST
            for create returns 201. Sticking to doc.)"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Refund"
      security:
        - ApiKey: []
          ApiSecret: []
    get:
      tags:
        - Refunds
      summary: List Refunds
      description: List refunds with optional filtering.
      operationId: listRefunds
      parameters:
        - $ref: "#/components/parameters/paginationOffset"
        - $ref: "#/components/parameters/paginationPage"
        - $ref: "#/components/parameters/paginationLimit"
        - name: customer.id
          in: query
          description: Filter refunds by Customer ID.
          required: false
          schema:
            type: string
            examples:
              - 00a70b35-2be3-4c43-aefb-397190134655
        - name: customer.externalId
          in: query
          description: Filter refunds by external Customer ID.
          required: false
          schema:
            type: string
            examples:
              - "134"
        - name: updatedAt
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/RangeQueryUpdateSpecs"
        - name: sortBy
          in: query
          description: Sort refunds by a specific column.
          required: false
          schema:
            type: string
            enum:
              - updatedAt
              - validatedAt
            default: updatedAt
        - name: sortOrder
          in: query
          description: Sort order.
          required: false
          schema:
            type: string
            enum:
              - DESC
              - ASC
            default: DESC
      responses:
        "200":
          description: Paginated list of refunds.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PaginationMetadata"
                  - type: object
                    required:
                      - items
                    properties:
                      items:
                        type: array
                        items:
                          $ref: "#/components/schemas/Refund"
      security:
        - ApiKey: []
          ApiSecret: []
  /refunds/{refund_id}:
    parameters:
      - name: refund_id
        in: path
        description: The Refund ID or `external:{externalId}`.
        required: true
        schema:
          type: string
        examples:
          default:
            value: 00a70b35-2be3-4c43-aefb-397190134655
    get:
      tags:
        - Refunds
      summary: Get Refund
      description: This endpoint can be used to retrieve the details of a specific refund by its ID.
      operationId: getRefund
      responses:
        "200":
          description: Refund details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Refund"
      security:
        - ApiKey: []
          ApiSecret: []
    delete:
      tags:
        - Refunds
      summary: Delete Refund
      description: This endpoint can be used to delete a specific refund by its ID.
      operationId: deleteRefund
      responses:
        "204":
          description: Refund deleted successfully.
      security:
        - ApiKey: []
          ApiSecret: []
  /reconcile:
    post:
      tags:
        - Operations
      summary: Reconcile Invoices, Credit Notes, Payments, Refunds
      description: |
        Manage a reconciliation, which assigns credit notes, payments and/or
        refunds previously created to existing invoices.

        A successful call will bind amounts and change invoices statuses
        accordingly.

        In order to avoid duplicating reconciliation, you have to provide a
        unique `externalId` to identify it.
      operationId: reconcile
      requestBody:
        description: Reconciliation details.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReconcileRequest"
      responses:
        "201":
          description: Reconciliation result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReconcileResponse"
      security:
        - ApiKey: []
          ApiSecret: []
  /custom_fields:
    post:
      tags:
        - Custom Fields
      summary: Create Custom Field
      description: This endpoint can be used to create a new custom field.
      operationId: createCustomField
      requestBody:
        description: Custom field definition.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomFieldAttribs"
      responses:
        "201":
          description: Custom Field Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomField"
        "400":
          description: Invalid Data Provided
          content:
            application/json:
              schema:
                type: object
                properties:
                  Error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        examples:
                          - INVALID_DATA
                      message:
                        type: string
                        examples:
                          - invalid data
                      details:
                        type: array
                        items:
                          type: object
                          properties:
                            field:
                              type: string
                              examples:
                                - dataType
                            error:
                              type: string
                              examples:
                                - custom_field_data_type expected
      security:
        - ApiKey: []
          ApiSecret: []
    get:
      tags:
        - Custom Fields
      summary: List Custom Fields
      description: List custom fields with optional pagination.
      operationId: listCustomFields
      parameters:
        - $ref: "#/components/parameters/paginationOffset"
        - $ref: "#/components/parameters/paginationPage"
        - $ref: "#/components/parameters/paginationLimit"
      responses:
        "200":
          description: Paginated list of custom fields.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PaginationMetadata"
                  - type: object
                    required:
                      - items
                    properties:
                      items:
                        type: array
                        items:
                          $ref: "#/components/schemas/CustomField"
      security:
        - ApiKey: []
          ApiSecret: []
  /custom_fields/{customFieldId}:
    parameters:
      - name: customFieldId
        in: path
        description: The Custom Field ID or `external:{externalId}`.
        required: true
        schema:
          type: string
        examples:
          default:
            value: 00a70b35-2be3-4c43-aefb-397190134655
    delete:
      tags:
        - Custom Fields
      summary: Delete Custom Field
      description: This endpoint can be used to delete a specific custom field by its ID.
      operationId: deleteCustomField
      responses:
        "204":
          description: Custom field deleted successfully.
      security:
        - ApiKey: []
          ApiSecret: []
  /actions:
    get:
      tags:
        - Actions
      summary: List Actions
      description: List actions with optional filtering.
      operationId: listActions
      parameters:
        - $ref: "#/components/parameters/paginationOffset"
        - $ref: "#/components/parameters/paginationPage"
        - $ref: "#/components/parameters/paginationLimit"
        - name: sortBy
          in: query
          description: Sort actions by a specific column.
          required: false
          schema:
            type: string
            enum:
              - createdAt
              - updatedAt
              - dueDate
              - performedAt
            default: createdAt
        - name: sortOrder
          in: query
          description: Sort order.
          required: false
          schema:
            type: string
            enum:
              - DESC
              - ASC
            default: DESC
        - name: updatedAt
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/RangeQueryUpdateSpecs"
        - name: dueDate
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/RangeQueryDueDateSpecs"
        - name: performedAt
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/RangeQueryPerformedAtSpecs"
        - name: state
          in: query
          description: Filter actions by state.
          required: false
          schema:
            $ref: "#/components/schemas/ActionState"
        - name: source
          in: query
          description: Filter actions by source.
          required: false
          schema:
            $ref: "#/components/schemas/ActionSource"
        - name: customerId
          in: query
          description: Filter actions by Customer ID.
          required: false
          schema:
            type: string
            format: uuid
            examples:
              - 00a70b35-2be3-4c43-aefb-397190134655
        - name: carryingInvoiceId
          in: query
          description: Filter actions by carrying invoice ID.
          required: false
          schema:
            type: string
            format: uuid
            examples:
              - 00a70b35-2be3-4c43-aefb-397190134655
        - name: assignedToUserId
          in: query
          description: Filter actions by assigned user ID.
          required: false
          schema:
            type: string
            format: uuid
            examples:
              - 00a70b35-2be3-4c43-aefb-397190134655
        - name: performedByUserId
          in: query
          description: Filter actions by the user who performed the action.
          required: false
          schema:
            type: string
            format: uuid
            examples:
              - 00a70b35-2be3-4c43-aefb-397190134655
      responses:
        "200":
          description: Paginated list of actions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionsListResponse"
      security:
        - ApiKey: []
          ApiSecret: []
  /actions/{actionId}:
    parameters:
      - name: actionId
        in: path
        description: The Action ID.
        required: true
        schema:
          type: string
          format: uuid
        examples:
          default:
            value: 00a70b35-2be3-4c43-aefb-397190134655
    get:
      tags:
        - Actions
      summary: Get Action
      description: This endpoint can be used to retrieve a specific action by its ID.
      operationId: getAction
      responses:
        "200":
          description: Action details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"
      security:
        - ApiKey: []
          ApiSecret: []
  /notes:
    post:
      tags:
        - Notes
      summary: Create Note
      description: This endpoint can be used to create a new note.
      operationId: createNote
      requestBody:
        description: Note data to create.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NoteCreation"
      responses:
        "201":
          description: Note Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Note"
      security:
        - ApiKey: []
          ApiSecret: []
    get:
      tags:
        - Notes
      summary: List Notes
      description: List notes with optional filtering.
      operationId: listNotes
      parameters:
        - $ref: "#/components/parameters/paginationOffset"
        - $ref: "#/components/parameters/paginationPage"
        - $ref: "#/components/parameters/paginationLimit"
        - name: includeAttachments
          in: query
          description: Whether to include attachments in the response.
          required: false
          schema:
            type: boolean
            default: false
        - name: customerId
          in: query
          description: Filter notes by Customer ID.
          required: false
          schema:
            type: string
            format: uuid
            examples:
              - 00a70b35-2be3-4c43-aefb-397190134655
        - name: userId
          in: query
          description: Filter notes by User ID.
          required: false
          schema:
            type: string
            format: uuid
            examples:
              - 00a70b35-2be3-4c43-aefb-397190134655
        - name: invoiceId
          in: query
          description: Filter notes by Invoice ID.
          required: false
          schema:
            type: string
            format: uuid
            examples:
              - 00a70b35-2be3-4c43-aefb-397190134655
        - name: createdAt
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/RangeQueryCreationSpecs"
        - name: updatedAt
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/RangeQueryUpdateSpecs"
        - name: modifiedAt
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/RangeQueryContentModificationSpecs"
        - name: sortBy
          in: query
          description: Sort notes by a specific column.
          required: false
          schema:
            type: string
            enum:
              - createdAt
              - updatedAt
              - modifiedAt
            examples:
              - createdAt
              - updatedAt
              - modifiedAt
        - name: sortOrder
          in: query
          description: Sort order.
          required: false
          schema:
            type: string
            enum:
              - DESC
              - ASC
            default: DESC
      responses:
        "200":
          description: Paginated list of notes.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PaginationMetadata"
                  - type: object
                    required:
                      - items
                    properties:
                      items:
                        type: array
                        items:
                          $ref: "#/components/schemas/Note"
      security:
        - ApiKey: []
          ApiSecret: []
  /notes/{noteId}:
    parameters:
      - name: noteId
        in: path
        description: The Note ID.
        required: true
        schema:
          type: string
          format: uuid
        examples:
          default:
            value: 00a70b35-2be3-4c43-aefb-397190134655
    get:
      tags:
        - Notes
      summary: Get Note
      description: This endpoint can be used to retrieve a specific note by its ID.
      operationId: getNote
      responses:
        "200":
          description: Note details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Note"
      security:
        - ApiKey: []
          ApiSecret: []
    put:
      tags:
        - Notes
      summary: Update Note
      description: This endpoint can be used to update the contents of a note created via the API.
      operationId: updateNote
      requestBody:
        description: Note data to update.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NoteUpdate"
      responses:
        "200":
          description: Note Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Note"
        "403":
          description: Forbidden - Cannot update a note created from the UI
          content:
            application/json:
              schema:
                type: object
                properties:
                  Error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        examples:
                          - ACCESS_FORBIDDEN
                      message:
                        type: string
                        examples:
                          - Can only update notes created via API
      security:
        - ApiKey: []
          ApiSecret: []
    delete:
      tags:
        - Notes
      summary: Delete Note
      description: This endpoint can be used to delete a specific note by its ID.
      operationId: deleteNote
      responses:
        "204":
          description: Note deleted successfully.
        "403":
          description: Forbidden - Cannot delete a note created from the UI
          content:
            application/json:
              schema:
                type: object
                properties:
                  Error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        examples:
                          - ACCESS_FORBIDDEN
                      message:
                        type: string
                        examples:
                          - Can only delete notes created via API
      security:
        - ApiKey: []
          ApiSecret: []
  /notes/{noteId}/attachments:
    parameters:
      - name: noteId
        in: path
        description: The Note ID.
        required: true
        schema:
          type: string
          format: uuid
        examples:
          default:
            value: 00a70b35-2be3-4c43-aefb-397190134655
    post:
      tags:
        - Notes
      summary: Upload Note Attachment
      description: |
        This endpoint can be used to upload a file attachment to a note.
        You can either send the file in a multipart/form-data request (i.e. a regular "file upload" in HTML)
        or a JSON request with the file encoded in base64.

        Limitations:
        - Maximum file size: 5MB
      operationId: addNoteAttachment
      requestBody:
        description: File to attach to the note.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NoteAttachmentImportAttr"
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: The file to attach to the note.
                  contentMediaType: application/octet-stream
              required:
                - file
      responses:
        "201":
          description: Attachment created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NoteAttachment"
        "403":
          description: Forbidden - Cannot add attachments to a note created from the UI
          content:
            application/json:
              schema:
                type: object
                properties:
                  Error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        examples:
                          - ACCESS_FORBIDDEN
                      message:
                        type: string
                        examples:
                          - Can only add attachments to notes created via API
        "404":
          description: Note not found.
      security:
        - ApiKey: []
          ApiSecret: []
  /notes/{noteId}/attachments/{attachmentId}:
    parameters:
      - name: noteId
        in: path
        description: The Note ID.
        required: true
        schema:
          type: string
          format: uuid
        examples:
          default:
            value: 00a70b35-2be3-4c43-aefb-397190134655
      - name: attachmentId
        in: path
        description: The Attachment ID.
        required: true
        schema:
          type: string
          format: uuid
        examples:
          default:
            value: 7b2d4e6f-8a1c-4d3e-9f5b-0c6a2e8d1b3f
    delete:
      tags:
        - Notes
      summary: Delete Note Attachment
      description: This endpoint can be used to delete an attachment from a note.
      operationId: deleteNoteAttachment
      responses:
        "204":
          description: Attachment deleted successfully.
        "403":
          description: Forbidden - Cannot delete attachments from a note created from the UI
          content:
            application/json:
              schema:
                type: object
                properties:
                  Error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        examples:
                          - ACCESS_FORBIDDEN
                      message:
                        type: string
                        examples:
                          - Can only delete attachments from notes created via API
        "404":
          description: Note or attachment not found.
      security:
        - ApiKey: []
          ApiSecret: []
  /dunning_plans:
    get:
      tags:
        - Dunning Plans
      summary: List Dunning Plans
      description:
        List dunning plans (workflows) configured for your organization. Use
        this endpoint to discover the `id` of a dunning plan that can then be
        referenced on customers or invoices.
      operationId: listDunningPlans
      parameters:
        - $ref: "#/components/parameters/paginationOffset"
        - $ref: "#/components/parameters/paginationPage"
        - $ref: "#/components/parameters/paginationLimit"
      responses:
        "200":
          description: Paginated list of dunning plans.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PaginationMetadata"
                  - type: object
                    required:
                      - items
                    properties:
                      items:
                        type: array
                        items:
                          $ref: "#/components/schemas/DunningPlan"
      security:
        - ApiKey: []
          ApiSecret: []
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
    ApiSecret:
      type: apiKey
      in: header
      name: X-Api-Secret
  schemas:
    AccountManager:
      type: object
      description: User assigned as an account manager.
      properties:
        user:
          $ref: "#/components/schemas/User"
        createdAt:
          type: string
          format: date-time
          description: The date at which the user was assigned (ISO 8601 format).
    ACHDebitCustomerPaymentMethod:
      type: object
      properties:
        enabled:
          type: boolean
          description: Change whether ACH debit payments are enabled for this customer.
    Action:
      type: object
      description: Represents an action.
      required:
        - id
        - name
        - type
        - customer
        - createdAt
        - dueDate
        - state
      properties:
        id:
          type: string
          format: uuid
          description: The Action ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        name:
          type: string
          description: The action's name.
          examples:
            - "1st reminder: payment not received"
        type:
          type: string
          enum:
            - EMAIL
            - SMS
            - CALL
            - TASK
            - LETTER
            - REGISTERED_LETTER
          description: The action's type
          examples:
            - EMAIL
        customer:
          $ref: "#/components/schemas/CustomerLite"
        createdAt:
          type: string
          format: date-time
          description: The date at which the action was created (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        dueDate:
          type: string
          format: date-time
          description: The date when the action is due (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        performedAt:
          type:
            - string
            - "null"
          format: date-time
          description: The date when the action was performed (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        state:
          $ref: "#/components/schemas/ActionState"
        dunningPlan:
          $ref: "#/components/schemas/DunningPlanLite"
        performedBy:
          allOf:
            - $ref: "#/components/schemas/UserLite"
          description: The user who performed the action.
          nullable: true
        assignedTo:
          type: array
          description: The users to whom the action is assigned.
          items:
            $ref: "#/components/schemas/UserLite"
        recipients:
          type: array
          description: List of recipients.
          items:
            type: object
            required:
              - type
            properties:
              type:
                type: string
                enum:
                  - EMAIL
                  - PHONE
                  - CONTACT
                  - MEMBER
                  - ALIAS
                description: Recipient type.
              phone:
                type:
                  - string
                description: Recipient phone number.
                examples:
                  - "+12673148110"
              email:
                type:
                  - string
                format: email
                description: Recipient email address.
                examples:
                  - contact@email.com
          examples:
            - - type: EMAIL
                email: recipient@company.com
              - type: CONTACT
                email: contact@email.com
                phone: "+12673148110"
        source:
          $ref: "#/components/schemas/ActionSource"
        updatedAt:
          type: string
          format: date-time
          description: The date at which the action was last updated (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        carryingInvoice:
          $ref: "#/components/schemas/InvoiceReference"
    ActionsListResponse:
      allOf:
        - $ref: "#/components/schemas/PaginationMetadata"
        - type: object
          required:
            - items
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/Action"
    ActionSource:
      type: string
      enum:
        - WORKFLOW
        - CAMPAIGN
        - BILLING
      description: The source of the action.
    ActionState:
      type: string
      enum:
        - TODO
        - IGNORED
        - EXECUTED
        - IN_PROGRESS
        - FAILED
      description: State of the action.
    BankAccount:
      type: object
      description: Represents a bank account.
      required:
        - id
        - currency
        - swift
        - accountNumber
        - isMain
      properties:
        id:
          type: string
          format: uuid
          description: The ID of the bank account.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        externalId:
          type: string
          description: Bank account external ID.
          examples:
            - bWwsZWZuem8g
        alias:
          type: string
          description: Descriptive name of the bank account.
          examples:
            - USA Account
        currency:
          $ref: "#/components/schemas/Currency"
        source:
          type: string
          description: Source of the bank account information.
          examples:
            - USER_DEFINED
        swift:
          type: string
          description: The SWIFT/BIC code of the bank.
          examples:
            - BOFAUS3N
        accountNumber:
          type: string
          description: The bank account number or IBAN for European accounts.
          examples:
            - FR1420041010050500013M02606
        routingNumber:
          type: string
          description:
            The routing transit number for the bank account. Required for US
            accounts, but optional for European accounts.
          examples:
            - "091000019"
        bankName:
          type: string
          description: The name of the bank.
          examples:
            - Bank Of America
        isMain:
          type: boolean
          description:
            Indicates if it's the main bank account that should be displayed by
            default on the customer portal.
          examples:
            - false
        region:
          type: string
          description: "The region of the bank account: `EU` or `US`."
          enum:
            - EU
            - US
          examples:
            - US
        createdAt:
          type: string
          format: date-time
          description: The date at which the bank account was created (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
    BankAccountReference:
      deprecated: true
      type: object
      description: Reference to a Bank Account.
      properties:
        id:
          type: string
          format: uuid
          description: The BankAccount ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
      required:
        - id
    CardCustomerPaymentMethod:
      type: object
      properties:
        enabled:
          type: boolean
          description: Change whether card payments are enabled for this customer.
    CheckCustomerPaymentMethod:
      type: object
      properties:
        enabled:
          type: boolean
          description: Change whether check payments are enabled for this customer.
    Contact:
      description: Contact details.
      allOf:
        - $ref: "#/components/schemas/ContactAttribs"
        - type: object
          required:
            - id
          properties:
            id:
              type: string
              format: uuid
              description: The contact ID.
              examples:
                - 00a70b35-2be3-4c43-aefb-397190134655
            positionId:
              type:
                - string
                - "null"
              format: uuid
              description: The custom contact position ID.
              examples:
                - c8490f71-8252-40b2-935a-fb93ade55867
            createdAt:
              type: string
              format: date-time
              description: The date at which the contact was created (ISO 8601 format).
              examples:
                - 2015-05-05T12:30:00Z
    ContactAttribs:
      type: object
      description: Attributes for creating or updating a contact.
      properties:
        firstName:
          type: string
          description: Contact first name.
          examples:
            - John
        lastName:
          type: string
          description: Contact last name.
          examples:
            - Doe
        phone:
          type: string
          description: Contact phone number.
          examples:
            - "+33678059778"
        email:
          type: string
          format: email
          description: Contact email (must be unique).
          examples:
            - john@example.com
        position:
          type: string
          description: Contact position label.
          examples:
            - ACCOUNTING
        externalId:
          type: string
          description: Contact custom external identifier.
          examples:
            - CONT123
        isMain:
          type: boolean
          description: Indicates if this is the main contact for the customer.
          examples:
            - true
        customFields:
          type: array
          description: List of contact's custom fields values.
          items:
            $ref: "#/components/schemas/CustomFieldValueAttribs"
      required:
        - email
    CreditNote:
      description: Represents a credit note.
      allOf:
        - $ref: "#/components/schemas/CreditNoteCommonAttribs"
        - type: object
          required:
            - id
            - customer
            - linkedInvoices
          properties:
            id:
              type: string
              format: uuid
              description: The Credit Note ID.
              examples:
                - 00a70b35-2be3-4c43-aefb-397190134655
            pdfUrl:
              type:
                - string
                - "null"
              format: uri
              description: URL to the credit note PDF.
              examples:
                - https://files.upflow.io/credit_note.pdf
            customer:
              $ref: "#/components/schemas/CustomerLite"
            linkedInvoices:
              type: array
              description: The list of invoices linked to this credit note.
              items:
                $ref: "#/components/schemas/LinkedInvoice"
            createdAt:
              type: string
              format: date-time
              description: The date at which the credit note was created (ISO 8601 format).
              examples:
                - 2015-05-05T12:30:00Z
            updatedAt:
              type: string
              format: date-time
              description: The date at which the credit note was last updated (ISO 8601 format).
              examples:
                - 2015-05-05T12:30:00Z
    CreditNoteAllocation:
      type: object
      description: Details of how a refund is allocated to a credit note.
      required:
        - linkedAmount
        - creditNote
      properties:
        linkedAmount:
          type: integer
          description: Refund's share linked to the credit note (in cents).
          examples:
            - 3000
        creditNote:
          $ref: "#/components/schemas/CreditNoteCommonAttribs"
    CreditNoteAllocationCreation:
      type: object
      description: Details for allocating a refund to a credit note during creation.
      required:
        - amountLinked
        - creditNote
      properties:
        amountLinked:
          type: integer
          description: Refund share to allocate to the credit note (in cents).
          examples:
            - 3000
        creditNote:
          $ref: "#/components/schemas/CreditNoteReference"
    CreditNoteCommonAttribs:
      type: object
      description: Common attributes for credit notes.
      required:
        - customId
        - currency
        - grossAmount
        - netAmount
      properties:
        customId:
          type: string
          description: Credit note custom identifier (e.g., document number).
          examples:
            - CN123
        externalId:
          type: string
          description: Credit note external identifier.
          examples:
            - 92842AB37
        issuedAt:
          type: string
          format: date-time
          description: The date at which the credit note was issued (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        dueDate:
          type: string
          format: date-time
          description:
            The date when the credit note is due (ISO 8601 format). Often same
            as issuedAt.
          examples:
            - 2015-05-05T12:30:00Z
        name:
          type: string
          description: The credit note name or description.
          examples:
            - Credit Note for returned goods
        currency:
          $ref: "#/components/schemas/Currency"
        grossAmount:
          type: integer
          description: Amount including taxes (in cents).
          examples:
            - 1700
        netAmount:
          type: integer
          description: Amount net of taxes (in cents).
          examples:
            - 1500
        updatedAt:
          type: string
          format: date-time
          description: The date at which the credit note was last updated (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
    CreditNoteCreation:
      description: Attributes required to create or update a credit note.
      allOf:
        - $ref: "#/components/schemas/CreditNoteCommonAttribs"
        - type: object
          required:
            - customer
          properties:
            customer:
              $ref: "#/components/schemas/CustomerReference"
            linkedInvoices:
              type: array
              description: The list of invoices to link to this credit note upon creation.
              items:
                $ref: "#/components/schemas/LinkedInvoiceCreation"
    CreditNoteReference:
      type: object
      description:
        Reference to a credit note, identifiable by ID, external ID, or
        custom ID.
      properties:
        id:
          type: string
          format: uuid
          description: The credit note ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        externalId:
          type: string
          description: The credit note external ID.
          examples:
            - AEGaaZD
        customId:
          type: string
          description: The credit note custom ID.
          examples:
            - AEGaaZD
      oneOf:
        - required:
            - id
        - required:
            - externalId
        - required:
            - customId
    CreditNoteRefWithAmount:
      description: Reference to a credit note with an associated amount.
      allOf:
        - $ref: "#/components/schemas/CreditNoteReference"
        - type: object
          required:
            - amountLinked
          properties:
            amountLinked:
              type: integer
              description: Amount allocated from the credit note (in cents).
              examples:
                - 3000
    CreditNotesListResponse:
      allOf:
        - $ref: "#/components/schemas/PaginationMetadata"
        - type: object
          required:
            - items
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/CreditNote"
    Currency:
      type: string
      description: ISO 4217 Currency Code
      enum:
        - EUR
        - CHF
        - USD
        - CAD
        - GBP
      examples:
        - EUR
    Customer:
      description: Represents a customer.
      allOf:
        - $ref: "#/components/schemas/CustomerAttribs"
        - type: object
          required:
            - id
            - countInvoicesDue
            - countInvoicesOverdue
            - balance
            - amountUnapplied
            - amountDue
            - amountOverdue
            - currency
            - directUrl
          properties:
            id:
              type: string
              format: uuid
              description: The Customer ID.
              examples:
                - 00a70b35-2be3-4c43-aefb-397190134655
            accountManagerId:
              deprecated: true
              type:
                - string
                - "null"
              format: uuid
              description:
                (Deprecated) ID of the User managing the Customer. This field is
                deprecated, use assignedUsers field or use the endpoint to update the customer assigned
                user list instead.
              examples:
                - 00a70b35-2be3-4c43-aefb-397190134655
            assignedUsers:
              type: array
              description: List of users assigned to the customer.
              items:
                $ref: "#/components/schemas/AccountManager"
            countInvoicesDue:
              type: integer
              format: int32
              description: The count of due invoices.
              examples:
                - 0
            countInvoicesOverdue:
              type: integer
              format: int32
              description: The count of overdue invoices.
              examples:
                - 1
            balance:
              type: integer
              description: Balance of the customer (in cents).
              examples:
                - 118000
            amountUnapplied:
              type: integer
              description: Unapplied transaction amount of the customer (in cents).
              examples:
                - 10000
            amountDue:
              type: integer
              description: The total amount that is due (in cents).
              examples:
                - 0
            amountOverdue:
              type: integer
              description: The total amount that is overdue (in cents).
              examples:
                - 118000
            averagePaymentDelay:
              type:
                - integer
                - "null"
              description:
                Average payment delay for this customer, in days. Computed by Upflow
                from the customer's invoices as a weighted average of each invoice's
                delay (paid invoices use the gap between payment and due date, unpaid
                invoices use the gap between today and due date), weighted by invoice
                amount. `null` if Upflow has not computed a value yet.
              examples:
                - 7
            currency:
              $ref: "#/components/schemas/Currency"
            directUrl:
              type: string
              format: uri
              description: The URL of the customer page in the Upflow UI.
              examples:
                - https://app.upflow.io/customers/ABCDEFGHI
            customFields:
              type: array
              description: List of customer's custom fields with values.
              items:
                $ref: "#/components/schemas/CustomFieldValue"
            dunningPaused:
              type: boolean
              description: Whether dunning is currently paused for this customer.
              examples:
                - false
            dunningPausedUntil:
              type:
                - string
                - "null"
              format: date
              description: The date until which dunning is paused (YYYY-MM-DD), or `null` if not paused.
              examples:
                - 2024-06-01
            dunningPausedComment:
              type:
                - string
                - "null"
              description: Comment provided when dunning was paused, or `null` if none.
              examples:
                - Customer requested delay until end of month.
            dunningPausedByUserId:
              type:
                - string
                - "null"
              format: uuid
              description: The ID of the user who paused dunning, or `null` if not paused.
              examples:
                - 00a70b35-2be3-4c43-aefb-397190134655
            lastActionId:
              type:
                - string
                - "null"
              format: uuid
              description: The ID of the last action executed on this customer, or `null` if none has been executed. Only actions in the EXECUTED state are taken into account; IGNORED and FAILED actions are excluded. Use the actions endpoints to retrieve the action itself, including its name, date and author.
              examples:
                - 00a70b35-2be3-4c43-aefb-397190134655
            nextActionId:
              type:
                - string
                - "null"
              format: uuid
              description: The ID of the next action scheduled for this customer, or `null` if none is scheduled. Use the actions endpoints to retrieve the action itself.
              examples:
                - 00a70b35-2be3-4c43-aefb-397190134655
            createdAt:
              type: string
              format: date-time
              description: The date at which the customer was created in Upflow (ISO 8601 format).
              examples:
                - 2015-05-05T12:30:00Z
    CustomerAttribs:
      type: object
      description: Attributes for creating or updating a customer.
      required:
        - name
      properties:
        name:
          type: string
          description:
            Customer name. Cannot be updated if customer comes from an external
            source system.
          examples:
            - Upflow SAS
        vatNumber:
          type: string
          description:
            Customer VAT number. Cannot be updated if customer comes from an
            external source system.
          examples:
            - "838718328"
        accountingRef:
          type: string
          deprecated: true
          description:
            (Deprecated) Customer accounting reference (used in accounting tool).
            Use a custom field instead. Cannot be updated if customer comes from an external
            source system.
          examples:
            - UPFL-SAS
        externalId:
          type: string
          description:
            An external ID that uniquely references the customer. Cannot be
            updated if customer comes from an external source system.
          examples:
            - 1a2c3b
        accountManagerId:
          type:
            - string
            - "null"
          format: uuid
          deprecated: true
          description: (Deprecated) ID of the User managing the Customer. Use assignedUsers instead.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        assignedUsers:
          type: array
          description: List of user IDs to assign to the customer. Cannot be updated if customers comes from an external source system.
          items:
            type: string
            format: uuid
          examples:
            - - 00a70b35-2be3-4c43-aefb-397190134655
        dunningPlanId:
          type:
            - string
            - "null"
          format: uuid
          description: ID of the dunning plan.
          examples:
            - 7a6c91dc-3580-4c43-aefb-397190134655
        address:
          type: object
          properties:
            address:
              type: string
              description:
                Street address. Cannot be updated if customer comes from an
                external source system.
              examples:
                - 25 Passage Dubail
            zipcode:
              type: string
              description:
                Zip code. Cannot be updated if customer comes from an external
                source system.
              examples:
                - "75010"
            city:
              type: string
              description:
                City name. Cannot be updated if customer comes from an external
                source system.
              examples:
                - Paris
            state:
              type: string
              description:
                State. Cannot be updated if customer comes from an external source
                system.
              examples:
                - Île-de-France
            country:
              type: string
              description:
                Country. Cannot be updated if customer comes from an external
                source system.
              examples:
                - France
        parent:
          $ref: "#/components/schemas/CustomerReference"
          description:
            A reference to the customer's parent company, if applicable. Cannot
            be updated if customer comes from an external source system.
        paymentMethods:
          $ref: "#/components/schemas/CustomerPaymentMethods"
          description:
            Configures the payment methods available to this customer. A method
            can only be enabled for a customer if it is enabled first in your
            organization.
        customFields:
          type: array
          description: List of customer's custom fields values.
          items:
            $ref: "#/components/schemas/CustomFieldValueAttribs"
    CustomerLite:
      type: object
      description: Minimal customer information.
      required:
        - id
        - companyName
      properties:
        id:
          type: string
          format: uuid
          description: The Customer ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        externalId:
          type: string
          description: An external ID that uniquely references the customer.
          examples:
            - 1a2c3b
        companyName:
          type: string
          description: Customer name.
          examples:
            - Upflow SAS
        accountingRef:
          type: string
          deprecated: true
          description:
            (Deprecated) Customer accounting reference (used in accounting tool).
            Use a custom field instead.
          examples:
            - UPFL-SAS
    CustomerNoteCreation:
      description: Attributes required to create a customer note. The note won't be linked to any particular invoice.
      allOf:
        - $ref: "#/components/schemas/NoteCreationBase"
        - type: object
          required:
            - customerId
          properties:
            customerId:
              type: string
              format: uuid
              description: The ID of the customer to associate with this note.
              examples:
                - 00a70b35-2be3-4c43-aefb-397190134655
    CustomerPaymentMethods:
      type: object
      description: Configuration for payment methods available to a customer.
      properties:
        card:
          $ref: "#/components/schemas/CardCustomerPaymentMethod"
        check:
          $ref: "#/components/schemas/CheckCustomerPaymentMethod"
        achDebit:
          $ref: "#/components/schemas/ACHDebitCustomerPaymentMethod"
        sepaDebit:
          $ref: "#/components/schemas/SEPADebitCustomerPaymentMethod"
        goCardless:
          $ref: "#/components/schemas/GoCardlessCustomerPaymentMethod"
        wireTransfer:
          $ref: "#/components/schemas/WireTransferCustomerPaymentMethod"
    CustomerReference:
      type: object
      description: Reference to a customer, identifiable by ID or external ID.
      properties:
        id:
          type: string
          format: uuid
          description: The Customer ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        externalId:
          type: string
          description: An external ID that uniquely references the customer.
          examples:
            - 1a2c3b
      oneOf:
        - required:
            - id
        - required:
            - externalId
    CustomField:
      description: Represents a custom field definition.
      allOf:
        - $ref: "#/components/schemas/CustomFieldAttribs"
        - type: object
          required:
            - id
          properties:
            id:
              type: string
              format: uuid
              description: The Custom Field ID.
              examples:
                - 00a70b35-2be3-4c43-aefb-397190134655
            source:
              type:
                - string
                - "null"
              description: Source of the custom field definition.
              examples:
                - USER_DEFINED
    CustomFieldAttribs:
      type: object
      description: Attributes for defining a custom field.
      required:
        - externalId
        - label
        - dataType
        - entityType
      properties:
        externalId:
          type: string
          description: Custom field external identifier.
          examples:
            - AEGaaZD
        label:
          type: string
          description: Custom field label displayed in the UI.
          examples:
            - custom field 01
        description:
          type:
            - string
            - "null"
          description: Custom field description.
          examples:
            - custom field 01 description
        dataType:
          $ref: "#/components/schemas/CustomFieldDataType"
        entityType:
          $ref: "#/components/schemas/CustomFieldEntityType"
    CustomFieldDataType:
      type: string
      enum:
        - STRING
        - BOOLEAN
        - FLOAT
        - DATE
        - DATETIME
        - SELECT
        - MULTI_SELECT
      description: Data type of the custom field.
    CustomFieldEntityType:
      type: string
      enum:
        - CUSTOMER
        - INVOICE
        - CONTACT
      description: The type of entity the custom field applies to.
    CustomFieldAnyValue:
      oneOf:
        - type: integer
          format: int32
          description: Integer value.
        - type: string
          description: String value (could also be date-time or date).
        - type: boolean
          description: Boolean value.
        - $ref: "#/components/schemas/CustomFieldValueOption"
          description: Value for SELECT type.
        - type: array
          items:
            $ref: "#/components/schemas/CustomFieldValueOption"
          description: Value for MULTI_SELECT type.
      description: >
        The value of the custom field. Can be a primitive (string, integer,
        boolean), a single object for SELECT types, an array of objects for
        MULTI_SELECT types.
    CustomFieldValue:
      type: object
      description: A custom field value as returned when reading an entity.
      required:
        - id
        - label
        - dataType
        - value
        - source
      properties:
        id:
          type: string
          format: uuid
          description: The Custom Field ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        label:
          type: string
          description: Custom field label displayed in the UI.
          examples:
            - Account ID
        dataType:
          $ref: "#/components/schemas/CustomFieldDataType"
        source:
          type:
            - string
            - "null"
          description: Source of the custom field value.
          examples:
            - USER_DEFINED
        value:
          $ref: "#/components/schemas/CustomFieldAnyValue"
    CustomFieldValueAttribs:
      type: object
      description: >
        Attributes for setting a custom field value. Identify the field by
        id or externalId.
      properties:
        id:
          type:
            - string
            - "null"
          format: uuid
          description: The Custom Field ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        externalId:
          type:
            - string
            - "null"
          description: Custom field external identifier.
          examples:
            - AEGaaZD
        value:
          $ref: "#/components/schemas/CustomFieldAnyValue"
    CustomFieldValueOption:
      type: object
      properties:
        externalId:
          type:
            - string
            - "null"
          description: External identifier for the option.
        label:
          type: string
          description: Display label for the option.
      required:
        - label
    DunningPlan:
      type: object
      description: Represents a dunning plan (also known as a workflow).
      required:
        - id
        - name
        - entity
        - mode
        - default
        - maximumContactFrequency
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: The dunning plan ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        name:
          type: string
          description: The dunning plan name.
          examples:
            - Standard dunning plan
        entity:
          type: string
          description: The entity this dunning plan applies to.
          enum:
            - CUSTOMER
            - INVOICE
          examples:
            - CUSTOMER
        mode:
          type: string
          description: The dunning plan mode.
          enum:
            - STANDARD
            - CONTEXTUAL
          examples:
            - STANDARD
        default:
          type: boolean
          description:
            Whether this dunning plan is the default for the organization.
          examples:
            - true
        maximumContactFrequency:
          type: integer
          format: int32
          description: Minimum number of days between two contacts with a customer.
          examples:
            - 5
        emailReplyTo:
          type: string
          description:
            Reply-to email used on messages sent through this dunning plan.
            Omitted when not configured.
          examples:
            - reply@example.com
        createdAt:
          type: string
          format: date-time
          description: The date at which the dunning plan was created (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        updatedAt:
          type: string
          format: date-time
          description: The date at which the dunning plan was last updated (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
    DunningPlanLite:
      type: object
      description: Minimal dunning plan information.
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
          description: The Dunning plan ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        name:
          type: string
          description: The dunning plan name.
          examples:
            - Standard dunning plan
    GoCardlessCustomerPaymentMethod:
      type: object
      properties:
        enabled:
          type: boolean
          description: Change whether GoCardless payments are enabled for this customer.
    Invoice:
      description: Represents an invoice.
      allOf:
        - $ref: "#/components/schemas/InvoiceCommonAttribs"
        - type: object
          required:
            - id
            - state
          properties:
            id:
              type: string
              format: uuid
              description: The Invoice ID.
              examples:
                - 00a70b35-2be3-4c43-aefb-397190134655
            customerId:
              type:
                - string
                - "null"
              format: uuid
              description: Customer ID associated with the invoice.
              examples:
                - a1b2c3
            payments:
              type: array
              description: List of payments associated with the invoice.
              items:
                $ref: "#/components/schemas/PaymentsObject"
            pdfUrl:
              type:
                - string
                - "null"
              format: uri
              description: URL to the invoice PDF.
              examples:
                - http://example.com/invoice.pdf
            state:
              $ref: "#/components/schemas/InvoiceStatus"
            customFields:
              type: array
              description: List of invoice's custom fields with values.
              items:
                $ref: "#/components/schemas/CustomFieldValue"
              examples:
                - []
            dunningPaused:
              type: boolean
              description: Whether dunning is currently paused for this invoice.
              examples:
                - false
            dunningPausedUntil:
              type:
                - string
                - "null"
              format: date
              description: The date until which dunning is paused (YYYY-MM-DD), or `null` if not paused.
              examples:
                - 2024-06-01
            dunningPausedComment:
              type:
                - string
                - "null"
              description: Comment provided when dunning was paused, or `null` if none.
              examples:
                - Customer requested delay until end of month.
            dunningPausedByUserId:
              type:
                - string
                - "null"
              format: uuid
              description: The ID of the user who paused dunning, or `null` if not paused.
              examples:
                - 00a70b35-2be3-4c43-aefb-397190134655
            promiseToPay:
              $ref: "#/components/schemas/InvoicePromiseToPay"
            createdAt:
              type: string
              format: date-time
              description: The date at which the invoice was created (ISO 8601 format).
              examples:
                - 2015-05-05T12:30:00Z
            updatedAt:
              type: string
              format: date-time
              description: The date at which the invoice was last updated (ISO 8601 format).
              examples:
                - 2015-05-05T12:30:00Z
    InvoiceAllocation:
      type: object
      description: Details of how a payment is allocated to an invoice.
      required:
        - linkedAmount
        - invoice
      properties:
        linkedAmount:
          type: integer
          description: Payment share allocated to the invoice (in cents).
          examples:
            - 3000
        invoice:
          $ref: "#/components/schemas/InvoiceLite"
    InvoiceAllocationCreation:
      type: object
      description: Details for allocating a payment to an invoice during creation.
      required:
        - amountLinked
        - invoice
      properties:
        amountLinked:
          type: integer
          description: Payment share to allocate to the invoice (in cents).
          examples:
            - 3000
        invoice:
          $ref: "#/components/schemas/InvoiceAllocationCreationInvoice"
    InvoiceAllocationCreationInvoice:
      description: Reference to an invoice for allocation, identifiable by ID,
        external ID, or custom ID.
      properties:
        id:
          type: string
          format: uuid
          description: The invoice ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        externalId:
          type: string
          description: The invoice external ID.
          examples:
            - AEGaaZD
        customId:
          type: string
          description: The invoice custom ID.
          examples:
            - AEGaaZD
      oneOf:
        - required:
            - id
        - required:
            - externalId
        - required:
            - customId
    InvoiceCommonAttribs:
      type: object
      description: Common attributes for invoices.
      required:
        - currency
        - grossAmount
        - netAmount
        - amountOutstanding
      properties:
        externalId:
          type: string
          description: Invoice external identifier.
          examples:
            - FAC123
        issuedAt:
          type: string
          format: date-time
          description: The date at which the invoice was issued (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        dueDate:
          type: string
          format: date-time
          description: The date when the invoice is due (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        name:
          type: string
          description: The invoice name or description.
          examples:
            - Facture couvrant les prestations de service de Decembre
        currency:
          $ref: "#/components/schemas/Currency"
        grossAmount:
          type: integer
          description: Amount including taxes (in cents).
          examples:
            - 2200
        netAmount:
          type: integer
          description: Amount net of taxes (in cents).
          examples:
            - 2000
        amountOutstanding:
          type: integer
          description: Amount currently outstanding on the invoice (in cents).
          examples:
            - 500
        dunningPlanId:
          type:
            - string
            - "null"
          format: uuid
          description: Dunning plan ID associated with the invoice.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
    InvoiceCommonAttribsNoPDF:
      type: object
      description: Attributes for creating or updating an invoice without providing a PDF.
      required:
        - customId
        - issuedAt
        - dueDate
        - currency
        - grossAmount
        - netAmount
        - customer
      properties:
        customId:
          type: string
          description: Invoice custom identifier.
          examples:
            - FAC123
        externalId:
          type: string
          description: Invoice external identifier.
          examples:
            - "54654321"
        issuedAt:
          type: string
          format: date-time
          description: The date at which the invoice was issued (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        dueDate:
          type: string
          format: date-time
          description: The date when the invoice is due (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        name:
          type: string
          description: The invoice name or description.
          examples:
            - Facture couvrant les prestations de service de Decembre
        currency:
          $ref: "#/components/schemas/Currency"
        grossAmount:
          type: integer
          description: Amount including taxes (in cents).
          examples:
            - 2200
        netAmount:
          type: integer
          description: Amount net of taxes (in cents).
          examples:
            - 2000
        customer:
          $ref: "#/components/schemas/CustomerReference"
        customFields:
          type: array
          description: List of invoice's custom fields values.
          items:
            $ref: "#/components/schemas/CustomFieldValueAttribs"
        promiseToPay:
          $ref: "#/components/schemas/PromiseToPay"
        dunningPlanId:
          type:
            - string
            - "null"
          format: uuid
          description: Dunning plan ID associated with the invoice.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
    InvoiceLite:
      type: object
      description: Minimal invoice information.
      required:
        - id
        - currency
        - status
        - amountOutstanding
        - grossAmount
        - netAmount
        - issuedAt
        - dueDate
      properties:
        id:
          type: string
          format: uuid
          description: The Invoice ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        currency:
          $ref: "#/components/schemas/Currency"
        status:
          $ref: "#/components/schemas/InvoiceStatus"
        amountOutstanding:
          type: integer
          description: Outstanding amount (in cents).
          examples:
            - 1500
        customId:
          type: string
          description: Invoice custom identifier.
          examples:
            - FAC123
        grossAmount:
          type: integer
          description: Amount including taxes (in cents).
          examples:
            - 2200
        netAmount:
          type: integer
          description: Amount net of taxes (in cents).
          examples:
            - 2000
        name:
          type: string
          description: The invoice name or description.
          examples:
            - Facture couvrant les prestations de service de Decembre
        issuedAt:
          type: string
          format: date-time
          description: The date at which the invoice was issued (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        dueDate:
          type: string
          format: date-time
          description: The date when the invoice is due (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        paidDate:
          type:
            - string
            - "null"
          format: date-time
          description: The date when the invoice was paid (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        externalId:
          type: string
          description: Invoice external identifier.
          examples:
            - 92842AB37
    InvoiceNoteCreation:
      description: Attributes required to create an invoice note. The note will be linked to the customer of this invoice.
      allOf:
        - $ref: "#/components/schemas/NoteCreationBase"
        - type: object
          required:
            - invoiceId
          properties:
            invoiceId:
              type: string
              format: uuid
              description: The ID of the invoice to associate with this note.
              examples:
                - 00a70b35-2be3-4c43-aefb-397190134655
    InvoicePromiseToPay:
      type:
        - object
        - "null"
      description: The promise to pay currently set on the invoice, or `null` if there is none.
      required:
        - expectedDate
        - comment
        - isActive
        - createdAt
      properties:
        expectedDate:
          type: string
          format: date
          description: Expected payment date (YYYY-MM-DD).
          examples:
            - 2023-08-30
        comment:
          type:
            - string
            - "null"
          description: Comment related to the promise to pay, or `null` if none was provided.
          examples:
            - Customer confirmed payment will be sent next week.
        isActive:
          type: boolean
          description: Whether the promise to pay is still active.
          examples:
            - true
        createdAt:
          type: string
          format: date-time
          description: The date at which the promise to pay was created (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
    InvoiceReference:
      type: object
      description: Reference to an invoice, identifiable by ID, external ID, or custom ID.
      properties:
        id:
          type: string
          format: uuid
          description: Invoice ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        externalId:
          type: string
          description: Invoice external ID.
          examples:
            - 92842AB37
        customId:
          type: string
          description: Invoice custom ID.
          examples:
            - FAC123
    InvoiceRefWithAmount:
      description: Reference to an invoice with an associated amount.
      allOf:
        - $ref: "#/components/schemas/InvoiceReference"
        - type: object
          required:
            - amountLinked
          properties:
            amountLinked:
              type: integer
              description: Amount allocated to the invoice (in cents).
              examples:
                - 2000
    InvoiceStatus:
      type: string
      enum:
        - DUE
        - OVERDUE
        - PAID
        - WRITTEN_OFF
        - DISPUTED
      description: Status of the invoice.
    InvoiceUpdateAttribs:
      type: object
      description: Attributes allowed for updating an invoice.
      properties:
        customFields:
          type: array
          description: List of invoice's custom fields values to update.
          items:
            $ref: "#/components/schemas/CustomFieldValueAttribs"
        promiseToPay:
          $ref: "#/components/schemas/PromiseToPay"
        dunningPlanId:
          type:
            - string
            - "null"
          format: uuid
          description: Dunning plan ID associated with the invoice.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
    LegacyInvoiceCommonAttribsNoPDF:
      type: object
      description:
        (Deprecated) Attributes for creating an invoice via the legacy
        endpoint. Use InvoiceCommonAttribsNoPDF instead.
      required:
        - customId
        - issuedAt
        - dueDate
        - currency
        - grossAmount
        - netAmount
      properties:
        customId:
          type: string
          description: Invoice custom identifier.
          examples:
            - FAC123
        externalId:
          type: string
          description: Invoice external identifier.
          examples:
            - "54654321"
        issuedAt:
          type: string
          format: date-time
          description: The date at which the invoice was issued (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        dueDate:
          type: string
          format: date-time
          description: The date when the invoice is due (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        name:
          type: string
          description: The invoice name or description.
          examples:
            - Facture couvrant les prestations de service de Decembre
        currency:
          $ref: "#/components/schemas/Currency"
        grossAmount:
          type: integer
          description: Amount including taxes (in cents).
          examples:
            - 2200
        netAmount:
          type: integer
          description: Amount net of taxes (in cents).
          examples:
            - 2000
        customFields:
          type: array
          description: List of invoice's custom fields values.
          items:
            $ref: "#/components/schemas/CustomFieldValueAttribs"
        promiseToPay:
          $ref: "#/components/schemas/PromiseToPay"
        dunningPlanId:
          type:
            - string
            - "null"
          format: uuid
          description: Dunning plan ID associated with the invoice.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
    LinkedInvoice:
      type: object
      description: Details of an invoice linked to another document (e.g., credit note).
      required:
        - amountLinked
        - invoice
      properties:
        amountLinked:
          type: integer
          description: Amount allocated to the invoice (in cents).
          examples:
            - 2000
        invoice:
          $ref: "#/components/schemas/InvoiceLite"
    LinkedInvoiceCreation:
      type: object
      description: Reference to an invoice and the amount to link.
      required:
        - amountLinked
        - invoice
      properties:
        amountLinked:
          type: integer
          description: Amount allocated to the invoice (in cents).
          examples:
            - 2000
        invoice:
          $ref: "#/components/schemas/InvoiceReference"
          description: Descriptor for the invoice to link.
    Note:
      type: object
      description: Represents a note.
      required:
        - id
        - createdAt
        - updatedAt
        - customer
        - body
      properties:
        id:
          type: string
          format: uuid
          description: The Note ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        createdAt:
          type: string
          format: date-time
          description: The date at which the note was created (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        updatedAt:
          type: string
          format: date-time
          description: The date at which the note was last updated (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        modifiedAt:
          type: string
          format: date-time
          nullable: true
          description: The date of the last user edit to the note contents (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        customer:
          allOf:
            - $ref: "#/components/schemas/CustomerLite"
          description: The customer associated with this note.
        user:
          allOf:
            - $ref: "#/components/schemas/UserLite"
          description: The user who created the note. Null if the note was created using the API.
          nullable: true
        invoice:
          allOf:
            - $ref: "#/components/schemas/InvoiceReference"
          description: The invoice associated with this note.
          nullable: true
        body:
          allOf:
            - $ref: "#/components/schemas/RichTextDocument"
        medium:
          type: string
          description: The medium through which the note was created.
          enum:
            - UI
            - API
          examples:
            - UI
        attachments:
          type: array
          description: Array of files attached to this note.
          items:
            $ref: "#/components/schemas/NoteAttachment"
    NoteAttachment:
      type: object
      required:
        - id
        - mimeType
        - fileName
        - createdAt
        - fileUrl
      properties:
        id:
          type: string
          format: uuid
          description: The Attachment ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        mimeType:
          type: string
          description: The MIME type of the attached file.
          examples:
            - image/png
            - application/pdf
        fileName:
          type: string
          description: The name of the attached file.
          examples:
            - document.pdf
            - screenshot.png
        createdAt:
          type: string
          format: date-time
          description: The date at which the attachment was created (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        fileUrl:
          type: string
          format: uri
          description: The URL to download the attached file. Valid for 10 hours.
          examples:
            - https://example.com/files/document.pdf
    NoteAttachmentImportAttr:
      type: object
      description: Attributes for importing a note attachment via JSON.
      properties:
        fileName:
          type: string
          description: The name of the file.
        data:
          type: string
          description: Base64 encoded string for the file. Mandatory when using
            application/json.
          examples:
            - JVBERi0xLjYNJeLjz9MNCjE5IDAgb2JqDTw8L0Zp...DSUlRU9GDQ==
          contentEncoding: base64
      required:
        - fileName
        - data
    NoteCreation:
      description: Attributes required to create a note. Either customerId or invoiceId must be provided.
      oneOf:
        - $ref: "#/components/schemas/CustomerNoteCreation"
        - $ref: "#/components/schemas/InvoiceNoteCreation"
    NoteCreationBase:
      type: object
      description: Common attributes for note creation.
      required:
        - body
      properties:
        body:
          allOf:
            - $ref: "#/components/schemas/RichTextDocument"
    NoteUpdate:
      type: object
      description: Attributes required to update a note. Only notes created via the API can be updated.
      required:
        - body
      properties:
        body:
          allOf:
            - $ref: "#/components/schemas/RichTextDocument"
    PaginationMetadata:
      type: object
      required:
        - limit
        - total
      properties:
        offset:
          type: integer
          format: int32
          description: 0-based index of the first item returned. Returned when using offset-based pagination or by default.
          examples:
            - 0
        page:
          type: integer
          format: int32
          description: Page number (1-based). Returned when using page-based pagination.
          examples:
            - 1
        limit:
          type: integer
          format: int32
          description: Maximum number of items returned.
          examples:
            - 50
        total:
          type: integer
          format: int32
          description: Total items in the set.
          examples:
            - 100
    Payment:
      description: Represents a payment transaction.
      allOf:
        - $ref: "#/components/schemas/PaymentCommonAttribs"
        - type: object
          required:
            - id
            - amountLinked
            - modifiedAt
            - linkedInvoices
          properties:
            id:
              type: string
              format: uuid
              description: The Payment ID.
              examples:
                - 00a70b35-2be3-4c43-aefb-397190134655
            type:
              $ref: "#/components/schemas/PaymentType"
            amountLinked:
              type: integer
              description: Amount allocated to invoices (in cents).
              examples:
                - 1700
            modifiedAt:
              type: string
              format: date-time
              description: The date when the payment was last updated (ISO 8601 format).
              examples:
                - 2015-05-05T12:30:00Z
              deprecated: true
            linkedInvoices:
              type: array
              description: List of linked invoices with the allocated amount.
              items:
                $ref: "#/components/schemas/InvoiceAllocation"
            customer:
              $ref: "#/components/schemas/CustomerLite"
            createdAt:
              type: string
              format: date-time
              description: The date at which the payment was created (ISO 8601 format).
              examples:
                - 2015-05-05T12:30:00Z
            updatedAt:
              type: string
              format: date-time
              description: The date at which the payment was last updated (ISO 8601 format).
              examples:
                - 2015-05-05T12:30:00Z
    PaymentAllocation:
      type: object
      description: Details of how a refund is allocated to a payment.
      required:
        - linkedAmount
        - payment
      properties:
        linkedAmount:
          type: integer
          description: Refund's share linked to the payment (in cents).
          examples:
            - 3000
        payment:
          $ref: "#/components/schemas/PaymentCommonAttribs"
    PaymentAllocationCreation:
      type: object
      description: Details for allocating a refund to a payment during creation.
      required:
        - amountLinked
        - payment
      properties:
        amountLinked:
          type: integer
          description: Refund share to allocate to the payment (in cents).
          examples:
            - 3000
        payment:
          $ref: "#/components/schemas/PaymentReference"
    PaymentCommonAttribs:
      type: object
      description: Common attributes for payments.
      required:
        - refNumber
        - currency
        - amount
        - validatedAt
      properties:
        refNumber:
          type: string
          description: Payment reference number.
          examples:
            - PYMT123
        currency:
          $ref: "#/components/schemas/Currency"
        amount:
          type: integer
          description: Payment amount (in cents).
          examples:
            - 1700
        instrument:
          $ref: "#/components/schemas/PaymentInstrument"
        validatedAt:
          type: string
          format: date-time
          description: The date when the payment is validated (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        externalId:
          type: string
          description: Payment external identifier.
          examples:
            - 92842AB37
        customFields:
          type: array
          description: List of payment's custom fields values.
          items:
            $ref: "#/components/schemas/CustomFieldValueAttribs"
    PaymentCreation:
      description: Attributes required to create or update a payment.
      allOf:
        - $ref: "#/components/schemas/PaymentCommonAttribs"
        - type: object
          properties:
            linkedInvoices:
              type: array
              description: List of invoices to link this payment to.
              items:
                $ref: "#/components/schemas/InvoiceAllocationCreation"
            customer:
              $ref: "#/components/schemas/CustomerReference"
              description:
                Customer reference (required if payment is not linked to invoices
                upon creation).
            state:
              $ref: "#/components/schemas/PaymentState"
    PaymentInstrument:
      type: string
      enum:
        - WIRE_TRANSFER
        - DIRECT_DEBIT
        - CARD
        - CASH
        - CHECK
        - UNKNOWN
      description: Instrument used for the payment.
    PaymentReference:
      type: object
      description: Reference to a payment, identifiable by ID or external ID.
      properties:
        id:
          type: string
          format: uuid
          description: The payment transaction ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        externalId:
          type: string
          description: The payment external ID.
          examples:
            - AEGaaZD
      oneOf:
        - required:
            - id
        - required:
            - externalId
    PaymentRefWithAmount:
      description: Reference to a payment with an associated amount.
      allOf:
        - $ref: "#/components/schemas/PaymentReference"
        - type: object
          required:
            - amountLinked
          properties:
            amountLinked:
              type: integer
              description: Payment share allocated (in cents).
              examples:
                - 3000
    PaymentsListResponse:
      allOf:
        - $ref: "#/components/schemas/PaginationMetadata"
        - type: object
          required:
            - items
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/Payment"
    PaymentsObject:
      type: object
      description: Simplified payment object, likely for display within an Invoice context.
      properties:
        id:
          type: string
          format: uuid
          description: The Payment ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        amount:
          type: integer
          description: Amount of payment (in cents).
          examples:
            - 1700
        linkedAmount:
          type: integer
          description: Amount of the payment allocated to this invoice (in cents).
          examples:
            - 1700
        executedAt:
          type: string
          format: date-time
          description: Payment execution date (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        instrument:
          $ref: "#/components/schemas/PaymentInstrument"
    PaymentState:
      type: string
      enum:
        - PENDING
        - VALIDATED
        - FAILED
        - CANCELLED
        - VOIDED
      description: State of the payment transaction.
    PaymentType:
      type: string
      enum:
        - ACCOUNT
        - MANUAL
        - PARSED_INVOICE
        - API
        - BATCH_IMPORT
        - NATIVE_INTEGRATION
      description: Source or method by which the payment was created.
    PDFImportAttr:
      type: object
      description: Attributes for importing a PDF via JSON.
      properties:
        data:
          type: string
          description:
            Base64 encoded string for the PDF file. Mandatory when using
            application/json.
          examples:
            - JVBERi0xLjYNJeLjz9MNCjE5IDAgb2JqDTw8L0Zp...DSUlRU9GDQ==
          contentEncoding: base64
      required:
        - data
    PromiseToPay:
      type: object
      description: Details of a promise to pay an invoice.
      required:
        - date
      properties:
        date:
          type: string
          format: date
          description: Expected payment date (YYYY-MM-DD).
          examples:
            - 2023-08-30
        comment:
          type: string
          description: Comment related to promise to pay.
          examples:
            - Customer confirmed payment will be sent next week.
        pauseDunning:
          type: boolean
          description: Pause dunning for the customer associated with this invoice.
          default: false
    RangeQueryContentModificationSpecs:
      title: Content modification range query params
      description: Only return entities for which content has been modified by a user during the given date range. (ISO 8601 format)
      type: object
      properties:
        modifiedAt.gt:
          description: Minimum value to filter by (exclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        modifiedAt.gte:
          description: Minimum value to filter by (inclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        modifiedAt.lt:
          description: Maximum value to filter by (exclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        modifiedAt.lte:
          description: Maximum value to filter by (inclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
    RangeQueryCreationSpecs:
      title: Creation range query params
      description: Only return entities that were created during the given date range. (ISO 8601 format)
      type: object
      properties:
        createdAt.gt:
          description: Minimum value to filter by (exclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        createdAt.gte:
          description: Minimum value to filter by (inclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        createdAt.lt:
          description: Maximum value to filter by (exclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        createdAt.lte:
          description: Maximum value to filter by (inclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
    RangeQueryDueDateSpecs:
      title: Due date range query params
      description: Only return entities that are due during the given date range. (ISO 8601 format)
      type: object
      properties:
        dueDate.gt:
          description: Minimum value to filter by (exclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        dueDate.gte:
          description: Minimum value to filter by (inclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        dueDate.lt:
          description: Maximum value to filter by (exclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        dueDate.lte:
          description: Maximum value to filter by (inclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
    RangeQueryModificationSpecs:
      title: Modification range query params
      description: Only return entities that were modified during the given date range. (ISO 8601 format)
      type: object
      properties:
        modifiedAt.gt:
          description: Minimum value to filter by (exclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        modifiedAt.gte:
          description: Minimum value to filter by (inclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        modifiedAt.lt:
          description: Maximum value to filter by (exclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        modifiedAt.lte:
          description: Maximum value to filter by (inclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
    RangeQueryPerformedAtSpecs:
      title: Performed at range query params
      description: Only return entities that were performed during the given date range. (ISO 8601 format)
      type: object
      properties:
        performedAt.gt:
          description: Minimum value to filter by (exclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        performedAt.gte:
          description: Minimum value to filter by (inclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        performedAt.lt:
          description: Maximum value to filter by (exclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        performedAt.lte:
          description: Maximum value to filter by (inclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
    RangeQueryUpdateSpecs:
      title: Update range query params
      description: Only return entities that were updated during the given date range. (ISO 8601 format)
      type: object
      properties:
        updatedAt.gt:
          description: Minimum value to filter by (exclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        updatedAt.gte:
          description: Minimum value to filter by (inclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        updatedAt.lt:
          description: Maximum value to filter by (exclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        updatedAt.lte:
          description: Maximum value to filter by (inclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
    RangeQueryValidationSpecs:
      title: Validation range query params
      description: Only return entities that were validated during the given date range. (ISO 8601 format)
      type: object
      properties:
        validatedAt.gt:
          description: Minimum value to filter by (exclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        validatedAt.gte:
          description: Minimum value to filter by (inclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        validatedAt.lt:
          description: Maximum value to filter by (exclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
        validatedAt.lte:
          description: Maximum value to filter by (inclusive)
          type: string
          format: date-time
          examples:
            - 2015-05-05T12:30:00Z
    ReconcileRequest:
      type: object
      description: Request body for reconciliation.
      required:
        - externalId
      properties:
        externalId:
          type: string
          description: A unique external identifier for this reconciliation operation.
          examples:
            - RECONCILE_BATCH_001
        invoices:
          type: array
          items:
            $ref: "#/components/schemas/InvoiceRefWithAmount"
          description: Invoices involved in the reconciliation and the amounts linked.
        payments:
          type: array
          items:
            $ref: "#/components/schemas/PaymentRefWithAmount"
          description: Payments involved in the reconciliation and the amounts linked.
        creditNotes:
          type: array
          items:
            $ref: "#/components/schemas/CreditNoteRefWithAmount"
          description: Credit notes involved in the reconciliation and the amounts linked.
        refunds:
          type: array
          items:
            $ref: "#/components/schemas/RefundRefWithAmount"
          description: Refunds involved in the reconciliation and the amounts linked.
    ReconcileResponse:
      type: string
      enum:
        - CREATED
        - UPDATED
        - IGNORED
        - UNCHANGED
        - DELETED
      description: Status of the reconciliation operation.
    Refund:
      description: Represents a refund transaction.
      allOf:
        - $ref: "#/components/schemas/RefundCommonAttributes"
        - type: object
          required:
            - id
            - amountLinked
            - modifiedAt
          properties:
            id:
              type: string
              format: uuid
              description: The Refund ID.
              examples:
                - 00a70b35-2be3-4c43-aefb-397190134655
            amountLinked:
              type: integer
              description: Amount linked to the refund (in cents).
              examples:
                - 1700
            modifiedAt:
              type: string
              format: date-time
              description: The date when the refund was last updated (ISO 8601 format).
              examples:
                - 2015-05-05T12:30:00Z
              deprecated: true
            linkedTransactions:
              deprecated: true
              type: array
              description:
                (Deprecated - likely replaced by linkedPayments) List of linked
                payments with the allocated amount.
              items:
                $ref: "#/components/schemas/PaymentAllocation"
            linkedPayments:
              type: array
              description: List of payments linked to this refund.
              items:
                $ref: "#/components/schemas/PaymentAllocation"
            linkedCreditNotes:
              type: array
              description: List of credit notes linked to this refund.
              items:
                $ref: "#/components/schemas/CreditNoteAllocation"
            customer:
              $ref: "#/components/schemas/CustomerLite"
            createdAt:
              type: string
              format: date-time
              description: The date at which the refund was created (ISO 8601 format).
              examples:
                - 2015-05-05T12:30:00Z
            updatedAt:
              type: string
              format: date-time
              description: The date at which the refund was last updated (ISO 8601 format).
              examples:
                - 2015-05-05T12:30:00Z
    RefundCommonAttributes:
      type: object
      description: Common attributes for refunds.
      required:
        - refNumber
        - currency
        - amount
        - validatedAt
      properties:
        refNumber:
          type: string
          description: Refund reference number.
          examples:
            - REFUND123
        currency:
          $ref: "#/components/schemas/Currency"
        amount:
          type: integer
          description: Refund amount (in cents).
          examples:
            - 1700
        instrument:
          $ref: "#/components/schemas/PaymentInstrument"
        validatedAt:
          type: string
          format: date-time
          description: The date when the refund is validated (ISO 8601 format).
          examples:
            - 2015-05-05T12:30:00Z
        externalId:
          type: string
          description: Refund external identifier.
          examples:
            - 92842AB37
    RefundCreation:
      description: Attributes required to create or update a refund.
      allOf:
        - $ref: "#/components/schemas/RefundCommonAttributes"
        - type: object
          properties:
            linkedPayments:
              type: array
              description: Payments to link to this refund.
              items:
                $ref: "#/components/schemas/PaymentAllocationCreation"
            linkedCreditNotes:
              type: array
              description: Credit notes to link to this refund.
              items:
                $ref: "#/components/schemas/CreditNoteAllocationCreation"
            customer:
              $ref: "#/components/schemas/CustomerReference"
              description:
                Customer reference (required if refund is not linked upon
                creation).
    RefundReference:
      type: object
      description: Reference to a refund, identifiable by ID or external ID.
      properties:
        id:
          type: string
          format: uuid
          description: The refund ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        externalId:
          type: string
          description: The refund external ID.
          examples:
            - AEGaaZD
      oneOf:
        - required:
            - id
        - required:
            - externalId
    RefundRefWithAmount:
      description: Reference to a refund with an associated amount.
      allOf:
        - $ref: "#/components/schemas/RefundReference"
        - type: object
          required:
            - amountLinked
          properties:
            amountLinked:
              type: integer
              description: Amount linked to the refund (in cents).
              examples:
                - 1700
    RichTextDocument:
      type: object
      description: |
        A document in Rich Text JSON format.
        In the UI, it is rendered with [Slate.js](https://docs.slatejs.org/).

        The document is a nested tree structure composed of the following node types:

        **Element nodes (blocks)**

        Block-level elements that structure the document content.
        - `type` (string): The element type. Supported values: `"paragraph"`.
        - `children` (array): An array of child nodes, which can be text nodes or inline element nodes.

        **Text nodes (leaves)**

        The lowest-level nodes containing the actual text content. Adjacent text segments with different formatting are represented as separate text nodes.
        - `text` (string): The text content.
        - `bold` (boolean, optional): Bold formatting.
        - `italic` (boolean, optional): Italic formatting.
        - `underline` (boolean, optional): Underline formatting.

        **Link nodes (inline elements)**

        Inline elements that wrap text nodes to create hyperlinks.
        - `type` (string): Always `"link"`.
        - `url` (string): The link URL.
        - `children` (array): An array of text nodes representing the link text.

        **Mention nodes (inline elements)**

        Inline elements that reference a user.
        - `type` (string): Always `"mention"`.
        - `member` (object): The referenced member.
          - `id` (string, uuid): The member's unique identifier.
          - `displayName` (string): The display name of the member.
          - `email` (string): The email address of the member.
      examples:
        - - type: paragraph
            children:
              - text: "A paragraph with "
              - text: bold
                bold: true
              - text: ", "
              - text: italic
                italic: true
              - text: " and "
              - text: underlined
                underline: true
              - text: " formatting."
          - type: paragraph
            children:
              - text: "Visit "
              - type: link
                url: https://example.com
                children:
                  - text: our website
              - text: " for more info."
          - type: paragraph
            children:
              - text: "Assigned to "
              - type: mention
                member:
                  id: 441fd378-caab-4053-a712-d6f4cc9b6e99
                  displayName: John Doe
                  email: john.doe@upflow.io
                children:
                  - text: ""
              - text: "."
    SEPADebitCustomerPaymentMethod:
      type: object
      properties:
        enabled:
          type: boolean
          description: Change whether SEPA debit payments are enabled for this customer.
    User:
      type: object
      description: Represents an Upflow user.
      required:
        - id
        - position
        - email
      properties:
        id:
          type: string
          format: uuid
          description: The User ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        position:
          $ref: "#/components/schemas/UserPosition"
        firstName:
          type: string
          examples:
            - John
        lastName:
          type: string
          examples:
            - Doe
        phone1:
          type:
            - string
            - "null"
          examples:
            - "+33609090909"
        phone2:
          type:
            - string
            - "null"
          examples:
            - "+33609090909"
        email:
          type: string
          format: email
          examples:
            - john@example.com
    UserListResponse:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: "#/components/schemas/User"
    UserLite:
      type: object
      description: Minimal user information.
      required:
        - id
        - email
      properties:
        id:
          type: string
          format: uuid
          description: The User ID.
          examples:
            - 00a70b35-2be3-4c43-aefb-397190134655
        firstName:
          type: string
          description: The user's first name.
          examples:
            - John
        lastName:
          type: string
          description: The user's last name.
          examples:
            - Doe
        email:
          type: string
          format: email
          description: The user's email address.
          examples:
            - user@email.com
    UserPosition:
      type: string
      enum:
        - ACCOUNT_MANAGER
        - FINANCE_USER
        - ACCOUNTANT
      description: The role or position of the user within Upflow.
    WireTransferCustomerPaymentMethod:
      type: object
      properties:
        enabled:
          type: boolean
          description:
            Change whether wire transfer payments are enabled for this
            customer. Setting to false will erase any bank account setting for
            this customer.
        bankAccount:
          $ref: "#/components/schemas/BankAccountReference"
          description:
            (Deprecated) Specify a singular bank account for the customer. If
            this field is assigned, it will remove all other enabled bank
            accounts and only keep the one indicated. Use `bankAccounts`
            instead.
        bankAccounts:
          type: array
          description:
            Specify the bank accounts that the customer can use. Leave
            `bankAccount` unassigned when using this field.
          items:
            $ref: "#/components/schemas/BankAccountReference"
  parameters:
    paginationOffset:
      name: offset
      in: query
      description: The 0-based index of the first item to return.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 0
        default: 0
        examples:
          - 0
    paginationPage:
      name: page
      in: query
      description: The page number to retrieve (1-based). If both `page` and `offset` are provided, `offset` takes priority.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        examples:
          - 1
    paginationLimit:
      name: limit
      in: query
      description: Maximum number of items to return per page.
      required: false
      schema:
        type: integer
        format: int32
        default: 50
        maximum: 500
        examples:
          - 100
    source:
      name: source
      in: query
      required: false
      schema:
        type: string
        enum:
          - USER_DEFINED
          - SALESFORCE
          - NETSUITE
          - SELLSY
          - QUICKBOOKSONLINE
          - STRIPE
          - STRIPE_EXPRESS
          - CHARGEBEE
          - XERO
          - ZUORA
          - SAGE_INTACCT
          - PENNYLANE
        example: USER_DEFINED
      description: Data source for the contact. Recommended when using a contact ID that is external to Upflow.
security:
  - ApiKey: []
    ApiSecret: []