Rutter Commerce API

openapi: 3.2.0
info:
  title: Rutter Commerce API
  version: '2024-08-31'
  description: 'Operations tagged Commerce across 2 of this provider''s published API definitions: rutter-openapi-2024-08-31.json, rutter-unified-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://production.rutterapi.com/versioned
  description: Production server
- url: https://sandbox.rutterapi.com/versioned
  description: Sandbox server
- url: https://sandbox.rutterapi.com
  description: Sandbox
tags:
- name: Commerce
paths:
  /commerce/metrics/{metricName}:
    get:
      summary: Fetch commerce metric
      operationId: fetchCommerceMetric
      parameters:
      - name: metricName
        in: path
        required: true
        description: The path of the commerce metric.
        schema:
          $ref: '#/components/schemas/CommerceMetricPathParam/properties/metricName'
      - name: access_token
        in: query
        required: true
        description: The access token of the connection.
        schema:
          $ref: '#/components/schemas/CommerceMetricsQueryParams/properties/access_token'
      - name: start_date
        in: query
        required: false
        description: ISO 8601 date or datetime the first bucket starts at, floored to the start of its bucket. Defaults to the last 30 days for `day` granularity, or the last 13 months for `month`.
        schema:
          $ref: '#/components/schemas/CommerceMetricsQueryParams/properties/start_date'
      - name: end_date
        in: query
        required: false
        description: ISO 8601 date or datetime the last bucket ends at. A date without a time covers the whole day. Defaults to now. A window may span at most 90 `day` buckets or 13 `month` buckets.
        schema:
          $ref: '#/components/schemas/CommerceMetricsQueryParams/properties/end_date'
      - name: granularity
        in: query
        required: false
        description: The size of each bucket in the response. Defaults to `month`. Buckets are aligned to UTC, so a `day` bucket runs from 00:00:00Z to 23:59:59.999Z.
        schema:
          $ref: '#/components/schemas/CommerceMetricsQueryParams/properties/granularity'
      - name: force_fetch
        in: query
        required: false
        description: Used to force a response even if the underlying connection has not finished its initial sync.
        schema:
          $ref: '#/components/schemas/CommerceMetricsQueryParams/properties/force_fetch'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregateCommerceMetricResponse'
      x-supported-platforms:
      - AMAZON
      - BIG_COMMERCE
      - EBAY
      - LAZADA
      - MAGENTO
      - PAYPAL
      - SHOPEE
      - SHOPIFY
      - SQUARE
      x-sandbox-supported-platforms: []
      tags:
      - Commerce
      x-summary-source: derived
    servers:
    - url: https://production.rutterapi.com/versioned
      description: Production server
    - url: https://sandbox.rutterapi.com/versioned
      description: Sandbox server
  /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
      security:
      - basicAuth: []
    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'
      security:
      - basicAuth: []
    servers:
    - url: https://production.rutterapi.com/versioned
      description: Production
    - url: https://sandbox.rutterapi.com
      description: Sandbox
  /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'
      security:
      - basicAuth: []
    servers:
    - url: https://production.rutterapi.com/versioned
      description: Production
    - url: https://sandbox.rutterapi.com
      description: Sandbox
  /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
      security:
      - basicAuth: []
    servers:
    - url: https://production.rutterapi.com/versioned
      description: Production
    - url: https://sandbox.rutterapi.com
      description: Sandbox
  /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
      security:
      - basicAuth: []
    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'
      security:
      - basicAuth: []
    servers:
    - url: https://production.rutterapi.com/versioned
      description: Production
    - url: https://sandbox.rutterapi.com
      description: Sandbox
  /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'
      security:
      - basicAuth: []
    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'
      security:
      - basicAuth: []
    servers:
    - url: https://production.rutterapi.com/versioned
      description: Production
    - url: https://sandbox.rutterapi.com
      description: Sandbox
  /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
      security:
      - basicAuth: []
    servers:
    - url: https://production.rutterapi.com/versioned
      description: Production
    - url: https://sandbox.rutterapi.com
      description: Sandbox
  /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'
      security:
      - basicAuth: []
    servers:
    - url: https://production.rutterapi.com/versioned
      description: Production
    - url: https://sandbox.rutterapi.com
      description: Sandbox
components:
  examples:
    AggregateMetric_Example:
      value:
        start_date: '2022-05-01T00:00:00.000Z'
        end_date: '2022-05-31T23:59:59.999Z'
        currency: USD
        value: '-1149613.2900'
    Connection_Example:
      value:
        id: 00000000-0000-0000-0000-000000000000
        orgId: 00000000-0000-0000-0000-000000000000
        platform: SHOPIFY
  schemas:
    CommerceMetricsQueryParams:
      type: object
      properties:
        start_date:
          type: string
          description: ISO 8601 date or datetime the first bucket starts at, floored to the start of its bucket. Defaults to the last 30 days for `day` granularity, or the last 13 months for `month`.
        end_date:
          type: string
          description: ISO 8601 date or datetime the last bucket ends at. A date without a time covers the whole day. Defaults to now. A window may span at most 90 `day` buckets or 13 `month` buckets.
        access_token:
          type: string
          format: uuid
          description: The access token of the connection.
        granularity:
          type: string
          enum:
          - day
          - month
          description: The size of each bucket in the response. Defaults to `month`. Buckets are aligned to UTC, so a `day` bucket runs from 00:00:00Z to 23:59:59.999Z.
        force_fetch:
          type: string
          enum:
          - 'true'
          - 'false'
          description: Used to force a response even if the underlying connection has not finished its initial sync.
      required:
      - access_token
    AggregateMetric:
      type: object
      properties:
        start_date:
          type: string
          description: The starting date from which we start aggregating activity (revenue, expenses, etc).
        end_date:
          type: string
          description: The date at which we stop aggregating activity (revenue, expenses, etc).
        currency:
          type: string
          description: If applicable, the currency used for the value returned.
        value:
          type: string
          description: The value of the requested metric for the time range described by the start and end date.
      required:
      - start_date
      - end_date
      - currency
      - value
      examples:
      - AggregateMetric_Example:
          $ref: '#/components/examples/AggregateMetric_Example'
    AggregateCommerceMetricResponse:
      type: object
      properties:
        checkpoint:
          type: string
          description: The [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp for the date at which the metric was last updated.
        active_customers:
          type: array
          items:
            $ref: '#/components/schemas/AggregateMetric'
          description: The metric value and important metadata that defines the method of calculation.
        refund_rate:
          type: array
          items:
            $ref: '#/components/schemas/AggregateMetric'
          description: The metric value and important metadata that defines the method of calculation.
        total_orders:
          type: array
          items:
            $ref: '#/components/schemas/AggregateMetric'
          description: The metric value and important metadata that defines the method of calculation.
        total_revenue:
          type: array
          items:
            $ref: '#/components/schemas/AggregateMetric'
          description: The metric value and important metadata that defines the method of calculation.
        connection:
          $ref: '#/components/schemas/Connection'
      required:
      - checkpoint
      - connection
    Connection:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The UUID of the connection. Generated by Rutter.
        orgId:
          type: string
          format: uuid
          description: Your organization id.
        platform:
          $ref: '#/components/schemas/Platform'
      required:
      - id
      - orgId
      - platform
      examples:
      - Connection_Example:
          $ref: '#/components/examples/Connection_Example'
    Platform:
      type: string
      enum:
      - AMAZON
      - EBAY
      - ETSY
      - FNAC
      - WALMART
      - SHOPEE
      - LAZADA
      - MERCADOLIBRE
      - ALIBABA
      - WAYFAIR
      - SHEIN
      - NOON
      - SHOPLINE
      - PRESTASHOP
      - SHOPIFY
      - MAGENTO
      - WOO_COMMERCE
      - SQUARESPACE
      - WIX
      - SHOPER
      - SHOPLAZZA
      - BIG_COMMERCE
      - SALLA
      - ZID
      - TIKTOKSHOP
      - COMMERCELAYER
      - WEBFLOW
      - GUMROAD
      - ECWID
      - PAYPAL
      - SQUARE
      - STRIPE
      - CLOVER
      - MOLLIE
      - PAYNL
      - AUTHORIZENET
      - RECHARGE
      - CHARGIFY
      - CHARGEBEE
      - RECURLY
      - KASHFLOW
      - SAGE_INTACCT
      - SAGE_INTACCT_V2
      - DYNAMICS365
      - DYNAMICS365FO
      - ZOHOBOOKS
      - EXACTONLINE
      - FREEAGENT
      - QUICKBOOKS
      - QUICKBOOKS_DESKTOP
      - FRESHBOOKS
      - XERO
      - SAGE_BUSINESS_CLOUD
      - SAGE_50
      - VISTA
      - NETSUITE
      - WAVE
      - DUALENTRY
      - CAMPFIRE
      - RILLET
      - SOFTLEDGER
      - VISMA
      - SPIRIS
      - LEXWARE
      - MONEYBIRD
      - SAGE200CLOUD
      - MX
      - PLAID
      - TELLER
      - RAMP
      - ODOO
      - ACUMATICA
      - FULFIL
      - TALLY
      - SAPBUSINESSONE
      - SAPS4HANA
      - WORKDAY
      - ANFIX
      - ORACLEFUSION
      - HOLDED
      - MYOBBUSINESS
      - FORTNOX
      - GOOGLE
      - FACEBOOK
      - TIKTOK
      - INTUIT_BANK_FEEDS
      - PLAID_BANK_FEEDS
      - SAGE
      - SAGE_BANK_FEEDS
      - YODLEE_BANK_FEEDS
      - QUICKBOOKS_HRIS
      - BAMBOO_HR
      - GUSTO
      - DEEL
      - RIPPLING
      description: The underlying platform.
    CommerceMetricPathParam:
      type: object
      properties:
        metricName:
          type: string
          enum:
          - total_revenue
          - total_orders
          - active_customers
          - refund_rate
          description: The path of the commerce metric.
      required:
      - metricName
    ProductVariant:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        price:
          type: number
          format: double
        sku:
          type: string
        inventory_quantity:
          type: integer
    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
    OrderLineItem:
      type: object
      properties:
        product_id:
          type: string
        variant_id:
          type: string
        quantity:
          type: integer
        unit_price:
          type: number
          format: double
    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
    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
    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'
    ProductCreate:
      type: object
      required:
      - title
      properties:
        title:
          type: string
        description:
          type: string
        price:
          type: number
          format: double
        currency:
          type: string
    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
  parameters:
    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
    XRutterVersion:
      name: X-Rutter-Version
      in: header
      required: true
      schema:
        type: string
        example: '2024-08-31'
      description: API version identifier
  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/
x-refined-from:
- rutter-openapi-2024-08-31.json
- rutter-unified-api-openapi.yml