openapi: 3.1.0
info:
  title: Rutter Unified API
  description: >-
    The Rutter Unified API provides a single RESTful interface connecting to over
    60 commerce, payments, and accounting platforms. It supports connection management,
    accounting data (accounts, transactions, invoices, bills, expenses), commerce data
    (orders, products, customers, stores), payments data, ads data, and banking data.
    All requests require Basic authentication using client_id and client_secret, plus
    an access_token query parameter to identify the specific connection.
  version: '2024-08-31'
  contact:
    name: Rutter Developer Documentation
    url: https://docs.rutter.com/
externalDocs:
  description: Rutter API Documentation
  url: https://docs.rutter.com/
servers:
  - url: https://production.rutterapi.com/versioned
    description: Production
  - url: https://sandbox.rutterapi.com
    description: Sandbox
security:
  - basicAuth: []
tags:
  - name: Connections
    description: Manage platform connections and authentication
  - name: Accounting
    description: Accounting data across platforms
  - name: Commerce
    description: Commerce and e-commerce data
  - name: Banking
    description: Banking and financial account data
  - name: Payments
    description: Payment transactions
  - name: Ads
    description: Advertising platform data
  - name: Webhooks
    description: Webhook configuration and management
paths:
  /connections:
    get:
      operationId: listConnections
      summary: List Connections
      description: Retrieve all connections for the authenticated client.
      tags:
        - Connections
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  connections:
                    type: array
                    items:
                      $ref: '#/components/schemas/Connection'
                  next_cursor:
                    type: string
        '401':
          description: Unauthorized
  /connections/{connectionId}:
    get:
      operationId: getConnection
      summary: Get Connection
      description: Retrieve details for a specific platform connection.
      tags:
        - Connections
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - name: connectionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '404':
          description: Connection not found
  /connections/token_exchange:
    post:
      operationId: exchangeToken
      summary: Exchange Token
      description: >-
        Exchange a Rutter Link public token for a permanent access token
        for the connected platform.
      tags:
        - Connections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - public_token
              properties:
                public_token:
                  type: string
                  description: The public token obtained from Rutter Link
      responses:
        '200':
          description: Access token returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
  /accounts:
    get:
      operationId: listAccounts
      summary: List Accounts
      description: Retrieve a list of chart of accounts entries from the connected accounting platform.
      tags:
        - Accounting
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
                  next_cursor:
                    type: string
        '401':
          description: Unauthorized
  /transactions:
    get:
      operationId: listTransactions
      summary: List Transactions
      description: Retrieve a list of financial transactions from the connected platform.
      tags:
        - Accounting
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
        - name: updated_at_min
          in: query
          schema:
            type: string
            format: date-time
          description: Filter transactions updated after this timestamp
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
                  next_cursor:
                    type: string
  /invoices:
    get:
      operationId: listInvoices
      summary: List Invoices
      description: Retrieve a list of invoices from the connected accounting platform.
      tags:
        - Accounting
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoices:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invoice'
                  next_cursor:
                    type: string
    post:
      operationId: createInvoice
      summary: Create Invoice
      description: Create a new invoice in the connected accounting platform.
      tags:
        - Accounting
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - name: Idempotency-Key
          in: header
          schema:
            type: string
          description: Unique key to ensure idempotent request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceCreate'
      responses:
        '200':
          description: Invoice created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
  /invoices/{invoiceId}:
    get:
      operationId: getInvoice
      summary: Get Invoice
      description: Retrieve a specific invoice by ID.
      tags:
        - Accounting
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - name: invoiceId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '404':
          description: Invoice not found
  /bills:
    get:
      operationId: listBills
      summary: List Bills
      description: Retrieve a list of bills (vendor invoices) from the connected accounting platform.
      tags:
        - Accounting
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  bills:
                    type: array
                    items:
                      $ref: '#/components/schemas/Bill'
                  next_cursor:
                    type: string
    post:
      operationId: createBill
      summary: Create Bill
      description: Create a new bill in the connected accounting platform.
      tags:
        - Accounting
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillCreate'
      responses:
        '200':
          description: Bill created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bill'
  /expenses:
    get:
      operationId: listExpenses
      summary: List Expenses
      description: Retrieve a list of expense records from the connected accounting platform.
      tags:
        - Accounting
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  expenses:
                    type: array
                    items:
                      $ref: '#/components/schemas/Expense'
                  next_cursor:
                    type: string
  /orders:
    get:
      operationId: listOrders
      summary: List Orders
      description: >-
        Retrieve a list of orders from the connected commerce platform.
        Supports expansions to include additional data.
      tags:
        - Commerce
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
        - name: expand
          in: query
          schema:
            type: string
            enum:
              - platform_data
          description: Expand response with additional platform-specific data
        - name: updated_at_min
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  next_cursor:
                    type: string
    post:
      operationId: createOrder
      summary: Create Order
      description: Create a new order in the connected commerce platform.
      tags:
        - Commerce
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreate'
      responses:
        '200':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Get Order
      description: Retrieve a specific order by ID.
      tags:
        - Commerce
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
  /orders/{orderId}/fulfillments:
    post:
      operationId: fulfillOrder
      summary: Fulfill Order
      description: Mark an order as fulfilled and provide fulfillment details.
      tags:
        - Commerce
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FulfillmentCreate'
      responses:
        '200':
          description: Fulfillment created
  /products:
    get:
      operationId: listProducts
      summary: List Products
      description: Retrieve a list of products from the connected commerce platform.
      tags:
        - Commerce
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
                  next_cursor:
                    type: string
    post:
      operationId: createProduct
      summary: Create Product
      description: Create a new product in the connected commerce platform.
      tags:
        - Commerce
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductCreate'
      responses:
        '200':
          description: Product created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
  /products/{productId}:
    get:
      operationId: getProduct
      summary: Get Product
      description: Retrieve a specific product by ID.
      tags:
        - Commerce
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
    put:
      operationId: updateProduct
      summary: Update Product
      description: Update an existing product in the connected commerce platform.
      tags:
        - Commerce
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - name: productId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductUpdate'
      responses:
        '200':
          description: Product updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
  /customers:
    get:
      operationId: listCustomers
      summary: List Customers
      description: Retrieve a list of customers from the connected commerce or accounting platform.
      tags:
        - Commerce
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  customers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  next_cursor:
                    type: string
  /customers/{customerId}:
    get:
      operationId: getCustomer
      summary: Get Customer
      description: Retrieve details for a specific customer.
      tags:
        - Commerce
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - name: customerId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
  /bank-accounts:
    get:
      operationId: listBankAccounts
      summary: List Bank Accounts
      description: Retrieve a list of bank accounts from the connected banking platform.
      tags:
        - Banking
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  bank_accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/BankAccount'
                  next_cursor:
                    type: string
  /ad-accounts:
    get:
      operationId: listAdAccounts
      summary: List Ad Accounts
      description: Retrieve a list of advertising accounts from the connected ads platform.
      tags:
        - Ads
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - $ref: '#/components/parameters/AccessToken'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ad_accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/AdAccount'
                  next_cursor:
                    type: string
  /config-webhooks:
    get:
      operationId: listWebhooks
      summary: List Webhooks
      description: Retrieve all configured webhooks for the authenticated client.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
    post:
      operationId: createWebhook
      summary: Create Webhook
      description: Configure a new webhook endpoint to receive event notifications.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
      responses:
        '200':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
  /config-webhooks/{webhookId}:
    delete:
      operationId: deleteWebhook
      summary: Delete Webhook
      description: Remove a webhook configuration.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/XRutterVersion'
        - name: webhookId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Webhook deleted
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Use client_id as username and client_secret as password.
        Encode as base64(client_id:client_secret).
  parameters:
    XRutterVersion:
      name: X-Rutter-Version
      in: header
      required: true
      schema:
        type: string
        example: '2024-08-31'
      description: API version identifier
    AccessToken:
      name: access_token
      in: query
      required: true
      schema:
        type: string
      description: Unique access token identifying the specific connection
    Cursor:
      name: cursor
      in: query
      schema:
        type: string
      description: Pagination cursor from previous response next_cursor field
  schemas:
    Connection:
      type: object
      properties:
        id:
          type: string
        platform:
          type: string
          description: The connected platform (e.g., quickbooks, shopify, amazon)
        status:
          type: string
          enum:
            - active
            - inactive
            - error
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Account:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
            - asset
            - liability
            - equity
            - revenue
            - expense
        currency:
          type: string
        balance:
          type: number
          format: double
        platform_id:
          type: string
    Transaction:
      type: object
      properties:
        id:
          type: string
        amount:
          type: number
          format: double
        currency:
          type: string
        date:
          type: string
          format: date
        description:
          type: string
        type:
          type: string
        account_id:
          type: string
    Invoice:
      type: object
      properties:
        id:
          type: string
        customer_id:
          type: string
        status:
          type: string
          enum:
            - draft
            - open
            - paid
            - voided
        amount_due:
          type: number
          format: double
        currency:
          type: string
        due_date:
          type: string
          format: date
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
    InvoiceCreate:
      type: object
      required:
        - customer_id
        - line_items
      properties:
        customer_id:
          type: string
        currency:
          type: string
        due_date:
          type: string
          format: date
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
    Bill:
      type: object
      properties:
        id:
          type: string
        vendor_id:
          type: string
        status:
          type: string
          enum:
            - draft
            - open
            - paid
            - voided
        amount_due:
          type: number
          format: double
        currency:
          type: string
        due_date:
          type: string
          format: date
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
    BillCreate:
      type: object
      required:
        - vendor_id
        - line_items
      properties:
        vendor_id:
          type: string
        currency:
          type: string
        due_date:
          type: string
          format: date
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
    Expense:
      type: object
      properties:
        id:
          type: string
        amount:
          type: number
          format: double
        currency:
          type: string
        date:
          type: string
          format: date
        description:
          type: string
        category:
          type: string
        account_id:
          type: string
    LineItem:
      type: object
      properties:
        description:
          type: string
        quantity:
          type: number
        unit_price:
          type: number
          format: double
        total_amount:
          type: number
          format: double
    Order:
      type: object
      properties:
        id:
          type: string
        customer_id:
          type: string
        status:
          type: string
          enum:
            - pending
            - processing
            - fulfilled
            - cancelled
        currency:
          type: string
        total_price:
          type: number
          format: double
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItem'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    OrderCreate:
      type: object
      required:
        - customer_id
        - line_items
      properties:
        customer_id:
          type: string
        currency:
          type: string
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItem'
    OrderLineItem:
      type: object
      properties:
        product_id:
          type: string
        variant_id:
          type: string
        quantity:
          type: integer
        unit_price:
          type: number
          format: double
    FulfillmentCreate:
      type: object
      properties:
        tracking_number:
          type: string
        tracking_url:
          type: string
        carrier:
          type: string
        line_items:
          type: array
          items:
            type: object
            properties:
              line_item_id:
                type: string
              quantity:
                type: integer
    Product:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
            - active
            - draft
            - archived
        price:
          type: number
          format: double
        currency:
          type: string
        variants:
          type: array
          items:
            $ref: '#/components/schemas/ProductVariant'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ProductCreate:
      type: object
      required:
        - title
      properties:
        title:
          type: string
        description:
          type: string
        price:
          type: number
          format: double
        currency:
          type: string
    ProductUpdate:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        price:
          type: number
          format: double
        status:
          type: string
    ProductVariant:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        price:
          type: number
          format: double
        sku:
          type: string
        inventory_quantity:
          type: integer
    Customer:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
        phone:
          type: string
        created_at:
          type: string
          format: date-time
    BankAccount:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
            - checking
            - savings
        balance:
          type: number
          format: double
        currency:
          type: string
        institution_name:
          type: string
    AdAccount:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        platform:
          type: string
        currency:
          type: string
        status:
          type: string
    Webhook:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        events:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
            - active
            - inactive
        created_at:
          type: string
          format: date-time
    WebhookCreate:
      type: object
      required:
        - url
        - events
      properties:
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
            enum:
              - connection.created
              - connection.updated
              - order.created
              - order.updated
              - product.created
              - product.updated