openapi: 3.0.3
info:
  title: Rutter Unified API
  description: >-
    Rutter is a unified API for commerce, accounting, and payments. A single
    integration reads and writes normalized business data across QuickBooks,
    Xero, NetSuite, Sage Intacct, Shopify, Amazon, Stripe, and other platforms.

    All requests are authenticated with HTTP Basic auth using your Rutter
    client_id as the username and secret as the password, and must include an
    `X-Rutter-Version` header pinning the API version (date-based, e.g.
    `2023-03-14`). Every data request is scoped to a specific end-user
    connection using the `access_token` query parameter obtained by exchanging
    a public token from Rutter Link.
  termsOfService: https://www.rutter.com/legal/terms-of-service
  contact:
    name: Rutter Support
    email: support@rutter.com
    url: https://docs.rutterapi.com
  version: '2023-03-14'
servers:
  - url: https://production.rutterapi.com/versioned
    description: Production
  - url: https://sandbox.rutterapi.com/versioned
    description: Sandbox
security:
  - basicAuth: []
tags:
  - name: Connections
    description: Manage end-user connections created via Rutter Link.
  - name: Accounting
    description: Normalized accounting data - accounts, ledger accounts, journal entries, invoices, bills, payments, expenses, transactions.
  - name: Commerce
    description: Normalized commerce data - orders, products, customers, transactions.
  - name: Payments
    description: Normalized payment-processor data - payments, payouts, balances, transactions.
  - name: Webhooks
    description: Register and manage webhook endpoints for sync and data events.
paths:
  /connections/access_token:
    post:
      operationId: exchangePublicToken
      tags:
        - Connections
      summary: Exchange a public token for a connection access token
      description: >-
        Exchange the `public_token` returned by Rutter Link for a permanent
        connection `access_token` used to scope subsequent data requests.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - public_token
              properties:
                public_token:
                  type: string
                  description: The public token returned from Rutter Link.
      responses:
        '200':
          description: The exchanged connection access token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  connection:
                    $ref: '#/components/schemas/Connection'
  /connections:
    get:
      operationId: listConnections
      tags:
        - Connections
      summary: List connections
      description: List all connections created under your Rutter application.
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of connections.
          content:
            application/json:
              schema:
                type: object
                properties:
                  connections:
                    type: array
                    items:
                      $ref: '#/components/schemas/Connection'
                  next_cursor:
                    type: string
                    nullable: true
  /connections/{id}:
    get:
      operationId: getConnection
      tags:
        - Connections
      summary: Get a connection
      description: Retrieve metadata for a single connection by its Rutter id.
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested connection.
          content:
            application/json:
              schema:
                type: object
                properties:
                  connection:
                    $ref: '#/components/schemas/Connection'
    delete:
      operationId: deleteConnection
      tags:
        - Connections
      summary: Delete a connection
      description: Delete a connection and revoke its access token.
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The connection was deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
  /accounting/accounts:
    get:
      operationId: listAccounts
      tags:
        - Accounting
      summary: List bank accounts
      description: List the bank/financial accounts for the connected accounting platform.
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of accounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
                  next_cursor:
                    type: string
                    nullable: true
  /accounting/ledger_accounts:
    get:
      operationId: listLedgerAccounts
      tags:
        - Accounting
      summary: List ledger accounts (chart of accounts)
      description: List the ledger accounts (chart of accounts) for the connected accounting platform.
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of ledger accounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ledger_accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/LedgerAccount'
                  next_cursor:
                    type: string
                    nullable: true
  /accounting/journal_entries:
    get:
      operationId: listJournalEntries
      tags:
        - Accounting
      summary: List journal entries
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of journal entries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  journal_entries:
                    type: array
                    items:
                      $ref: '#/components/schemas/JournalEntry'
                  next_cursor:
                    type: string
                    nullable: true
    post:
      operationId: createJournalEntry
      tags:
        - Accounting
      summary: Create a journal entry
      description: Write a journal entry back to the connected accounting platform.
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/AccessToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                journal_entry:
                  $ref: '#/components/schemas/JournalEntry'
      responses:
        '200':
          description: The created journal entry.
          content:
            application/json:
              schema:
                type: object
                properties:
                  journal_entry:
                    $ref: '#/components/schemas/JournalEntry'
  /accounting/invoices:
    get:
      operationId: listInvoices
      tags:
        - Accounting
      summary: List invoices
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of invoices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoices:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invoice'
                  next_cursor:
                    type: string
                    nullable: true
    post:
      operationId: createInvoice
      tags:
        - Accounting
      summary: Create an invoice
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/AccessToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                invoice:
                  $ref: '#/components/schemas/Invoice'
      responses:
        '200':
          description: The created invoice.
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice:
                    $ref: '#/components/schemas/Invoice'
  /accounting/bills:
    get:
      operationId: listBills
      tags:
        - Accounting
      summary: List bills
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of bills.
          content:
            application/json:
              schema:
                type: object
                properties:
                  bills:
                    type: array
                    items:
                      $ref: '#/components/schemas/Bill'
                  next_cursor:
                    type: string
                    nullable: true
  /accounting/payments:
    get:
      operationId: listAccountingPayments
      tags:
        - Accounting
      summary: List accounting payments
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of accounting payments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  payments:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccountingPayment'
                  next_cursor:
                    type: string
                    nullable: true
  /accounting/transactions:
    get:
      operationId: listAccountingTransactions
      tags:
        - Accounting
      summary: List accounting transactions
      description: List bank/ledger transactions from the connected accounting platform.
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of accounting transactions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccountingTransaction'
                  next_cursor:
                    type: string
                    nullable: true
  /commerce/orders:
    get:
      operationId: listOrders
      tags:
        - Commerce
      summary: List orders
      description: List orders from the connected commerce or marketplace platform.
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of orders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  next_cursor:
                    type: string
                    nullable: true
  /commerce/products:
    get:
      operationId: listProducts
      tags:
        - Commerce
      summary: List products
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of products.
          content:
            application/json:
              schema:
                type: object
                properties:
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
                  next_cursor:
                    type: string
                    nullable: true
  /commerce/customers:
    get:
      operationId: listCustomers
      tags:
        - Commerce
      summary: List customers
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of customers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  customers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  next_cursor:
                    type: string
                    nullable: true
  /commerce/transactions:
    get:
      operationId: listCommerceTransactions
      tags:
        - Commerce
      summary: List commerce transactions
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of commerce transactions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/CommerceTransaction'
                  next_cursor:
                    type: string
                    nullable: true
  /payments/payments:
    get:
      operationId: listPayments
      tags:
        - Payments
      summary: List payments
      description: List payments from the connected payment processor.
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of payments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  payments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payment'
                  next_cursor:
                    type: string
                    nullable: true
  /payments/payouts:
    get:
      operationId: listPayouts
      tags:
        - Payments
      summary: List payouts
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of payouts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  payouts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payout'
                  next_cursor:
                    type: string
                    nullable: true
  /payments/balances:
    get:
      operationId: listBalances
      tags:
        - Payments
      summary: List balances
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/AccessToken'
      responses:
        '200':
          description: The processor balances.
          content:
            application/json:
              schema:
                type: object
                properties:
                  balances:
                    type: array
                    items:
                      $ref: '#/components/schemas/Balance'
  /payments/transactions:
    get:
      operationId: listPaymentTransactions
      tags:
        - Payments
      summary: List payment transactions
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of payment transactions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentTransaction'
                  next_cursor:
                    type: string
                    nullable: true
  /webhooks:
    get:
      operationId: listWebhooks
      tags:
        - Webhooks
      summary: List webhooks
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
      responses:
        '200':
          description: A list of registered webhooks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
    post:
      operationId: createWebhook
      tags:
        - Webhooks
      summary: Create a webhook
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  format: uri
                enabled_events:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: The created webhook.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook:
                    $ref: '#/components/schemas/Webhook'
  /webhooks/{id}:
    delete:
      operationId: deleteWebhook
      tags:
        - Webhooks
      summary: Delete a webhook
      parameters:
        - $ref: '#/components/parameters/RutterVersion'
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The webhook was deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic auth. Username is your Rutter client_id, password is your
        Rutter secret. Requests must also include the `X-Rutter-Version`
        header and, for data endpoints, the `access_token` query parameter.
  parameters:
    RutterVersion:
      name: X-Rutter-Version
      in: header
      required: true
      description: Date-based API version to pin (e.g. 2023-03-14).
      schema:
        type: string
        example: '2023-03-14'
    AccessToken:
      name: access_token
      in: query
      required: true
      description: The connection access token that scopes the request to one end user.
      schema:
        type: string
    Cursor:
      name: cursor
      in: query
      required: false
      description: Opaque cursor for pagination, returned as next_cursor.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of records to return per page.
      schema:
        type: integer
        default: 50
        maximum: 500
  schemas:
    Connection:
      type: object
      properties:
        id:
          type: string
        platform:
          type: string
          description: The underlying platform, e.g. QUICKBOOKS, SHOPIFY, STRIPE.
        access_token:
          type: string
        last_synced_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
    Account:
      type: object
      properties:
        id:
          type: string
        platform_id:
          type: string
        name:
          type: string
        type:
          type: string
        currency_code:
          type: string
        balance:
          type: number
    LedgerAccount:
      type: object
      properties:
        id:
          type: string
        platform_id:
          type: string
        name:
          type: string
        nominal_code:
          type: string
          nullable: true
        classification:
          type: string
          description: Asset, Liability, Equity, Revenue, or Expense.
        status:
          type: string
        current_balance:
          type: number
        currency_code:
          type: string
    JournalEntry:
      type: object
      properties:
        id:
          type: string
        platform_id:
          type: string
        transaction_date:
          type: string
          format: date
        memo:
          type: string
          nullable: true
        currency_code:
          type: string
        line_items:
          type: array
          items:
            type: object
            properties:
              ledger_account_id:
                type: string
              description:
                type: string
                nullable: true
              net_amount:
                type: number
              type:
                type: string
                enum:
                  - DEBIT
                  - CREDIT
    Invoice:
      type: object
      properties:
        id:
          type: string
        platform_id:
          type: string
        customer_id:
          type: string
          nullable: true
        issue_date:
          type: string
          format: date
        due_date:
          type: string
          format: date
          nullable: true
        status:
          type: string
        total_amount:
          type: number
        currency_code:
          type: string
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
    Bill:
      type: object
      properties:
        id:
          type: string
        platform_id:
          type: string
        vendor_id:
          type: string
          nullable: true
        issue_date:
          type: string
          format: date
        due_date:
          type: string
          format: date
          nullable: true
        status:
          type: string
        total_amount:
          type: number
        currency_code:
          type: string
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
    AccountingPayment:
      type: object
      properties:
        id:
          type: string
        platform_id:
          type: string
        account_id:
          type: string
          nullable: true
        payment_date:
          type: string
          format: date
        amount:
          type: number
        currency_code:
          type: string
        type:
          type: string
          description: e.g. ACCOUNTS_RECEIVABLE or ACCOUNTS_PAYABLE.
    AccountingTransaction:
      type: object
      properties:
        id:
          type: string
        platform_id:
          type: string
        account_id:
          type: string
          nullable: true
        posted_date:
          type: string
          format: date
        amount:
          type: number
        currency_code:
          type: string
        description:
          type: string
          nullable: true
    LineItem:
      type: object
      properties:
        description:
          type: string
          nullable: true
        quantity:
          type: number
        unit_amount:
          type: number
        total_amount:
          type: number
        ledger_account_id:
          type: string
          nullable: true
    Order:
      type: object
      properties:
        id:
          type: string
        platform_id:
          type: string
        status:
          type: string
        customer_id:
          type: string
          nullable: true
        total_price:
          type: number
        currency_code:
          type: string
        created_at:
          type: string
          format: date-time
        line_items:
          type: array
          items:
            type: object
            properties:
              product_id:
                type: string
                nullable: true
              quantity:
                type: integer
              unit_price:
                type: number
    Product:
      type: object
      properties:
        id:
          type: string
        platform_id:
          type: string
        name:
          type: string
        status:
          type: string
        variants:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              sku:
                type: string
                nullable: true
              price:
                type: number
              inventory_quantity:
                type: integer
                nullable: true
    Customer:
      type: object
      properties:
        id:
          type: string
        platform_id:
          type: string
        email:
          type: string
          format: email
          nullable: true
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
    CommerceTransaction:
      type: object
      properties:
        id:
          type: string
        platform_id:
          type: string
        order_id:
          type: string
          nullable: true
        amount:
          type: number
        currency_code:
          type: string
        status:
          type: string
        processed_at:
          type: string
          format: date-time
    Payment:
      type: object
      properties:
        id:
          type: string
        platform_id:
          type: string
        amount:
          type: number
        currency_code:
          type: string
        status:
          type: string
        customer_id:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
    Payout:
      type: object
      properties:
        id:
          type: string
        platform_id:
          type: string
        amount:
          type: number
        currency_code:
          type: string
        status:
          type: string
        arrival_date:
          type: string
          format: date
          nullable: true
    Balance:
      type: object
      properties:
        currency_code:
          type: string
        available_amount:
          type: number
        pending_amount:
          type: number
    PaymentTransaction:
      type: object
      properties:
        id:
          type: string
        platform_id:
          type: string
        payment_id:
          type: string
          nullable: true
        payout_id:
          type: string
          nullable: true
        type:
          type: string
        amount:
          type: number
        fee:
          type: number
          nullable: true
        currency_code:
          type: string
        created_at:
          type: string
          format: date-time
    Webhook:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        enabled_events:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time