Rutter Collections API

openapi: 3.2.0
info:
  title: Rutter Collections API
  version: '2024-08-31'
  description: The Universal API for all major e-commerce platforms, accounting systems, and payment processors.
servers:
- url: https://production.rutterapi.com/versioned
  description: Production server
- url: https://sandbox.rutterapi.com/versioned
  description: Sandbox server
tags:
- name: Collections
paths:
  /collections:
    get:
      summary: List commerce collections
      operationId: listCommerceCollections
      parameters:
      - name: access_token
        in: query
        required: true
        description: The access token of the connection.
        schema:
          $ref: '#/components/schemas/ListCollectionsQuery/properties/access_token'
      - name: cursor
        in: query
        required: false
        description: Used to paginate to the next batch of objects. Should be a copy of the `next_cursor` value from the previous response.
        schema:
          $ref: '#/components/schemas/ListCollectionsQuery/properties/cursor'
      - name: limit
        in: query
        required: false
        description: Used to limit the number of returned objects. Defaults to 50.
        schema:
          $ref: '#/components/schemas/ListCollectionsQuery/properties/limit'
      - name: expand
        in: query
        required: false
        description: Include platform specific data (includes additional fields not provided by the Rutter object).
        schema:
          $ref: '#/components/schemas/ListCollectionsQuery/properties/expand'
      - name: created_at_max
        in: query
        required: false
        description: Used to filter objects with a `created_at` value less than or equal to the supplied value. Should be a [Unix time](https://en.wikipedia.org/wiki/Unix_time) in milliseconds.
        schema:
          $ref: '#/components/schemas/ListCollectionsQuery/properties/created_at_max'
      - name: created_at_min
        in: query
        required: false
        description: Used to filter objects with a `created_at` value greater than or equal to the supplied value. Should be a [Unix time](https://en.wikipedia.org/wiki/Unix_time) in milliseconds.
        schema:
          $ref: '#/components/schemas/ListCollectionsQuery/properties/created_at_min'
      - name: updated_at_max
        in: query
        required: false
        description: Used to filter objects with a `updated_at` value less than or equal to the supplied value. Should be a [Unix time](https://en.wikipedia.org/wiki/Unix_time) in milliseconds.
        schema:
          $ref: '#/components/schemas/ListCollectionsQuery/properties/updated_at_max'
      - name: updated_at_min
        in: query
        required: false
        description: Used to filter objects with a `updated_at` value greater than or equal to the supplied value. Should be a [Unix time](https://en.wikipedia.org/wiki/Unix_time) in milliseconds.
        schema:
          $ref: '#/components/schemas/ListCollectionsQuery/properties/updated_at_min'
      - 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/ListCollectionsQuery/properties/force_fetch'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCollectionResponseWithConnection'
              examples:
                ListCollectionResponseWithConnection_Example:
                  $ref: '#/components/examples/ListCollectionResponseWithConnection_Example'
      x-supported-platforms:
      - SHOPIFY
      x-sandbox-supported-platforms: []
      tags:
      - Collections
      x-summary-source: derived
  /collections/{id}:
    get:
      summary: Fetch commerce collection
      operationId: fetchCommerceCollection
      parameters:
      - name: id
        in: path
        required: true
        description: The unique ID of the object.
        schema:
          $ref: '#/components/schemas/IdPathParam/properties/id'
      - name: access_token
        in: query
        required: true
        description: The access token of the connection.
        schema:
          $ref: '#/components/schemas/CommonGetParamsWithIdType/properties/access_token'
      - name: id_type
        in: query
        required: false
        description: Used to indicate the type of `id` that is supplied. Defaults to `rutter`. Not currently supported on Sage Intacct or Sage Business Cloud.
        schema:
          $ref: '#/components/schemas/CommonGetParamsWithIdType/properties/id_type'
      - 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/CommonGetParamsWithIdType/properties/force_fetch'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseWithConnection'
              examples:
                CollectionResponseWithConnection_Example:
                  $ref: '#/components/examples/CollectionResponseWithConnection_Example'
      x-supported-platforms:
      - SHOPIFY
      x-sandbox-supported-platforms: []
      tags:
      - Collections
      x-summary-source: derived
components:
  schemas:
    ListCollectionsQuery:
      type: object
      properties:
        access_token:
          type: string
          format: uuid
          description: The access token of the connection.
        cursor:
          type: string
          description: Used to paginate to the next batch of objects. Should be a copy of the `next_cursor` value from the previous response.
        limit:
          type: integer
          description: Used to limit the number of returned objects. Defaults to 50.
        expand:
          type: array
          items:
            type: string
            enum:
            - platform_data
          description: Include platform specific data (includes additional fields not provided by the Rutter object).
        created_at_max:
          type: integer
          description: Used to filter objects with a `created_at` value less than or equal to the supplied value. Should be a [Unix time](https://en.wikipedia.org/wiki/Unix_time) in milliseconds.
        created_at_min:
          type: integer
          description: Used to filter objects with a `created_at` value greater than or equal to the supplied value. Should be a [Unix time](https://en.wikipedia.org/wiki/Unix_time) in milliseconds.
        updated_at_max:
          type: integer
          description: Used to filter objects with a `updated_at` value less than or equal to the supplied value. Should be a [Unix time](https://en.wikipedia.org/wiki/Unix_time) in milliseconds.
        updated_at_min:
          type: integer
          description: Used to filter objects with a `updated_at` value greater than or equal to the supplied value. Should be a [Unix time](https://en.wikipedia.org/wiki/Unix_time) in milliseconds.
        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
    CommonGetParamsWithIdType:
      type: object
      properties:
        access_token:
          type: string
          format: uuid
          description: The access token of the connection.
        id_type:
          type: string
          enum:
          - rutter
          - platform
          description: Used to indicate the type of `id` that is supplied. Defaults to `rutter`. Not currently supported on Sage Intacct or Sage Business Cloud.
        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
    ListCollectionResponseWithConnection:
      type: object
      properties:
        collections:
          type: array
          items:
            $ref: '#/components/schemas/Collection'
        next_cursor:
          type:
          - string
          - 'null'
        connection:
          $ref: '#/components/schemas/Connection'
      required:
      - collections
      - connection
      examples:
      - ListCollectionResponseWithConnection_Example:
          $ref: '#/components/examples/ListCollectionResponseWithConnection_Example'
    CollectionResponseWithConnection:
      type: object
      properties:
        collection:
          $ref: '#/components/schemas/Collection'
        connection:
          $ref: '#/components/schemas/Connection'
      required:
      - collection
      - connection
      examples:
      - CollectionResponseWithConnection_Example:
          $ref: '#/components/examples/CollectionResponseWithConnection_Example'
    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'
    Collection:
      type: object
      properties:
        id:
          type: string
          description: The Rutter generated unique ID of the collection.
          x-rutter-platforms:
            SHOPIFY: {}
        platform_id:
          type:
          - string
          - 'null'
          description: The platform specific ID of the collection.
          x-rutter-platforms:
            SHOPIFY: {}
        name:
          type: string
          description: The name of the collection.
          x-rutter-platforms:
            SHOPIFY: {}
        type:
          type: string
          enum:
          - custom
          - smart
          description: The type of the collection. `custom` collections have products added by hand. `smart` collections are rule-based and the platform computes their membership.
          x-rutter-platforms:
            SHOPIFY: {}
        description:
          type:
          - string
          - 'null'
          description: The description of the collection. May contain HTML.
        handle:
          type:
          - string
          - 'null'
          description: The URL-friendly unique identifier of the collection.
          x-rutter-platforms:
            SHOPIFY: {}
        sort_order:
          type:
          - string
          - 'null'
          description: The order in which products are shown in the collection, as reported by the platform (for example `manual`, `best-selling`, `alpha-asc`, `price-desc`).
          x-rutter-platforms:
            SHOPIFY: {}
        image:
          type:
          - object
          - 'null'
          properties:
            src:
              type: string
              description: The URL of the image.
          required:
          - src
          additionalProperties: false
          description: The image linked to the collection.
        created_at:
          type:
          - string
          - 'null'
          description: The [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp that the collection was created.
        updated_at:
          type:
          - string
          - 'null'
          description: The [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp that the collection was last updated.
          x-rutter-platforms:
            SHOPIFY: {}
        platform_data:
          type: object
          additionalProperties: {}
          description: The raw platform data corresponding to the Rutter object.
      required:
      - id
      - name
      - type
      - description
      - handle
      - sort_order
      - image
      - created_at
      - updated_at
      examples:
      - Collection_Example:
          $ref: '#/components/examples/Collection_Example'
    IdPathParam:
      type: object
      properties:
        id:
          type: string
          description: The unique ID of the object.
      required:
      - id
    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.
  examples:
    ListCollectionResponseWithConnection_Example:
      value:
        collections:
        - id: 00000000-0000-0000-0000-000000000000
          platform_id: '12345678'
          name: Summer Sale
          type: smart
          description: <p>Everything on sale this summer.</p>
          handle: summer-sale
          sort_order: best-selling
          image:
            src: https://cdn.shopify.com/s/files/1/0000/0000/collections/summer.jpg
          created_at: '2023-01-02T02:34:56.000Z'
          updated_at: '2023-01-02T02:34:56.000Z'
        next_cursor: MTY3NDgzMTk0Ml82MDY4ZDI0ZC02NGRmLTRmN2EtYTM0Ny0zN2ZmNjY5MGVmMjU=
        connection:
          id: 00000000-0000-0000-0000-000000000000
          orgId: 00000000-0000-0000-0000-000000000000
          platform: NETSUITE
    Collection_Example:
      value:
        id: 00000000-0000-0000-0000-000000000000
        platform_id: '12345678'
        name: Summer Sale
        type: smart
        description: <p>Everything on sale this summer.</p>
        handle: summer-sale
        sort_order: best-selling
        image:
          src: https://cdn.shopify.com/s/files/1/0000/0000/collections/summer.jpg
        created_at: '2023-01-02T02:34:56.000Z'
        updated_at: '2023-01-02T02:34:56.000Z'
    CollectionResponseWithConnection_Example:
      value:
        collection:
          id: 00000000-0000-0000-0000-000000000000
          platform_id: '12345678'
          name: Summer Sale
          type: smart
          description: <p>Everything on sale this summer.</p>
          handle: summer-sale
          sort_order: best-selling
          image:
            src: https://cdn.shopify.com/s/files/1/0000/0000/collections/summer.jpg
          created_at: '2023-01-02T02:34:56.000Z'
          updated_at: '2023-01-02T02:34:56.000Z'
        connection:
          id: 00000000-0000-0000-0000-000000000000
          orgId: 00000000-0000-0000-0000-000000000000
          platform: NETSUITE
    Connection_Example:
      value:
        id: 00000000-0000-0000-0000-000000000000
        orgId: 00000000-0000-0000-0000-000000000000
        platform: SHOPIFY