openapi: 3.1.0
info:
  title: Rutter Unified Accounting Commerce 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/
servers:
- url: https://production.rutterapi.com/versioned
  description: Production
- url: https://sandbox.rutterapi.com
  description: Sandbox
security:
- basicAuth: []
tags:
- name: Commerce
  description: Commerce and e-commerce data
paths:
  /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'
components:
  parameters:
    XRutterVersion:
      name: X-Rutter-Version
      in: header
      required: true
      schema:
        type: string
        example: '2024-08-31'
      description: API version identifier
    Cursor:
      name: cursor
      in: query
      schema:
        type: string
      description: Pagination cursor from previous response next_cursor field
    AccessToken:
      name: access_token
      in: query
      required: true
      schema:
        type: string
      description: Unique access token identifying the specific connection
  schemas:
    ProductUpdate:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        price:
          type: number
          format: double
        status:
          type: string
    Customer:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
        phone:
          type: string
        created_at:
          type: string
          format: date-time
    ProductVariant:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        price:
          type: number
          format: double
        sku:
          type: string
        inventory_quantity:
          type: integer
    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
    OrderLineItem:
      type: object
      properties:
        product_id:
          type: string
        variant_id:
          type: string
        quantity:
          type: integer
        unit_price:
          type: number
          format: double
    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'
    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
    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
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use client_id as username and client_secret as password. Encode as base64(client_id:client_secret).
externalDocs:
  description: Rutter API Documentation
  url: https://docs.rutter.com/