openapi: 3.0.3
info:
  title: Rutter Unified Accounting Commerce 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: Commerce
  description: Normalized commerce data - orders, products, customers, transactions.
paths:
  /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
components:
  schemas:
    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
    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
    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
  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'
    Cursor:
      name: cursor
      in: query
      required: false
      description: Opaque cursor for pagination, returned as next_cursor.
      schema:
        type: string
    AccessToken:
      name: access_token
      in: query
      required: true
      description: The connection access token that scopes the request to one end user.
      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
  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.