Rutter Subscriptions API

openapi: 3.2.0
info:
  title: Rutter Subscriptions 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: Subscriptions
paths:
  /subscriptions:
    get:
      summary: List commerce subscriptions
      operationId: listCommerceSubscriptions
      parameters:
      - name: access_token
        in: query
        required: true
        description: The access token of the connection.
        schema:
          $ref: '#/components/schemas/ListSubscriptionsQuery/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/ListSubscriptionsQuery/properties/cursor'
      - name: limit
        in: query
        required: false
        description: Used to limit the number of returned objects. Defaults to 50.
        schema:
          $ref: '#/components/schemas/ListSubscriptionsQuery/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/ListSubscriptionsQuery/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/ListSubscriptionsQuery/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/ListSubscriptionsQuery/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/ListSubscriptionsQuery/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/ListSubscriptionsQuery/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/ListSubscriptionsQuery/properties/force_fetch'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSubscriptionsResponse'
              examples:
                ListSubscriptionsResponse_Example:
                  $ref: '#/components/examples/ListSubscriptionsResponse_Example'
      x-supported-platforms:
      - CHARGEBEE
      - CHARGIFY
      - RECURLY
      - STRIPE
      x-sandbox-supported-platforms: []
      tags:
      - Subscriptions
      x-summary-source: derived
components:
  schemas:
    ListSubscriptionsQuery:
      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
    ListSubscriptionsResponse:
      type: object
      properties:
        subscriptions:
          $ref: '#/components/schemas/Subscriptions'
        next_cursor:
          type:
          - string
          - 'null'
        connection:
          $ref: '#/components/schemas/Connection'
      required:
      - subscriptions
      - next_cursor
      examples:
      - ListSubscriptionsResponse_Example:
          $ref: '#/components/examples/ListSubscriptionsResponse_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'
    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.
    Subscription:
      type: object
      properties:
        id:
          type: string
          description: The Rutter generated unique ID of the subscription.
          x-rutter-platforms:
            STRIPE: {}
        platform_id:
          type: string
          description: The platform specific ID of the subscription.
          x-rutter-platforms:
            STRIPE: {}
        platform_customer_id:
          type:
          - string
          - 'null'
          description: The platform specific ID of the customer linked to the subscription.
          x-rutter-platforms:
            STRIPE: {}
        iso_currency_code:
          type: string
          description: The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the subscription.
          x-rutter-platforms:
            STRIPE: {}
        status:
          type: string
          enum:
          - active
          - in_trial
          - canceled
          - paused
          - unknown
          description: 'Status of subscription. Possible values are: `active`, `in_trial`, `canceled`, `paused`, `unknown`'
          x-rutter-platforms:
            STRIPE: {}
        items:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionItem'
          description: An array of subscription items linked to the subscription.
          x-rutter-platforms:
            STRIPE: {}
        created_at:
          type: string
          description: The [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp that the subscription was created.
          x-rutter-platforms:
            STRIPE: {}
        updated_at:
          type: string
          description: The [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp that the subscription was last updated.
          x-rutter-platforms:
            STRIPE: {}
        platform_data:
          type: object
          additionalProperties: {}
          description: The raw platform data corresponding to the Rutter object.
      required:
      - id
      - platform_id
      - iso_currency_code
      - status
      - created_at
      - updated_at
      examples:
      - Subscription_Example:
          $ref: '#/components/examples/Subscription_Example'
    Subscriptions:
      type: array
      items:
        $ref: '#/components/schemas/Subscription'
    SubscriptionItem:
      type: object
      properties:
        platform_id:
          type:
          - string
          - 'null'
          description: The platform specific ID of the subscription line item.
          x-rutter-platforms:
            STRIPE: {}
        interval:
          type: string
          description: Frequency with which this subscription item is billed. Accepted values include `day`, `week`, `month`, and `year`.
          x-rutter-platforms:
            STRIPE: {}
        interval_count:
          type: number
          description: Number of intervals between subscription billings. For instance, if this is set to 3 and interval is set to month, the user would be billed every 3 months.
          x-rutter-platforms:
            STRIPE: {}
        quantity:
          type: number
          description: The number of products sold in the subscription.
          x-rutter-platforms:
            STRIPE: {}
        amount:
          type:
          - number
          - 'null'
          description: The total amount charged for the subscription line item.
          x-rutter-platforms:
            STRIPE: {}
        unit_amount:
          type:
          - number
          - 'null'
          description: The unit cost of the product sold in the subscription.
          x-rutter-platforms:
            STRIPE: {}
      required:
      - platform_id
      - interval
      - interval_count
      - quantity
      - amount
      - unit_amount
  examples:
    ListSubscriptionsResponse_Example:
      value:
        subscriptions:
        - id: 00000000-0000-0000-0000-000000000000
          platform_id: '12345678'
          platform_customer_id: '12345678'
          iso_currency_code: USD
          status: active
          items:
          - platform_id: '12345678'
            interval: month
            interval_count: 1
            quantity: 2
            amount: 24.68
            unit_amount: 12.34
          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: SHOPIFY
    Subscription_Example:
      value:
        id: 00000000-0000-0000-0000-000000000000
        platform_id: '12345678'
        platform_customer_id: '12345678'
        iso_currency_code: USD
        status: active
        items:
        - platform_id: '12345678'
          interval: month
          interval_count: 1
          quantity: 2
          amount: 24.68
          unit_amount: 12.34
        created_at: '2023-01-02T02:34:56.000Z'
        updated_at: '2023-01-02T02:34:56.000Z'
    Connection_Example:
      value:
        id: 00000000-0000-0000-0000-000000000000
        orgId: 00000000-0000-0000-0000-000000000000
        platform: SHOPIFY