List Subscriptions

Intent

Reads the available subscriptions as a pageable collection without changing them.

When to call it

Call this when an interface, sync, or support workflow needs to inspect subscriptions. Use the filters and paging controls shown below to limit the result.

Access boundary

Authorize the request with a token that carries subscriptions:read or subscriptions:write.

Successful result

A successful request returns 200. The response schema below defines the body your integration receives.

GET

subscriptions

List Subscriptions

curl --request GET \
  --url https://api.getruba.com/v1/subscriptions/ \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.getruba.com/v1/subscriptions/"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.getruba.com/v1/subscriptions/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getruba.com/v1/subscriptions/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getruba.com/v1/subscriptions/"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.getruba.com/v1/subscriptions/")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getruba.com/v1/subscriptions/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "amount": 123,
      "currency": "<string>",
      "recurring_interval_count": 123,
      "current_period_start": "2023-11-07T05:31:56Z",
      "current_period_end": "2023-11-07T05:31:56Z",
      "trial_start": "2023-11-07T05:31:56Z",
      "trial_end": "2023-11-07T05:31:56Z",
      "cancel_at_period_end": true,
      "canceled_at": "2023-11-07T05:31:56Z",
      "started_at": "2023-11-07T05:31:56Z",
      "ends_at": "2023-11-07T05:31:56Z",
      "ended_at": "2023-11-07T05:31:56Z",
      "customer_id": "<string>",
      "product_id": "<string>",
      "discount_id": "<string>",
      "checkout_id": "<string>",
      "customer_cancellation_comment": "<string>",
      "metadata": {},
      "customer": {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "metadata": {},
        "email_verified": true,
        "name": "John Doe",
        "billing_name": "John Doe",
        "billing_address": {
          "line1": "<string>",
          "line2": "<string>",
          "postal_code": "<string>",
          "city": "<string>",
          "state": "<string>"
        },
        "tax_id": {
          "[0]": "<string>"
        },
        "organization_id": "<string>",
        "deleted_at": "2023-11-07T05:31:56Z",
        "avatar_url": "https://www.gravatar.com/avatar/xxx?d=404",
        "external_id": "usr_1337",
        "email": "customer@example.com",
        "locale": "<string>",
        "default_payment_method_id": "<string>"
      },
      "product": {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "trial_interval_count": 123,
        "name": "<string>",
        "description": "<string>",
        "recurring_interval_count": 123,
        "is_recurring": true,
        "is_archived": true,
        "organization_id": "<string>",
        "metadata": {},
        "prices": [
          {
            "created_at": "2023-11-07T05:31:56Z",
            "modified_at": "2023-11-07T05:31:56Z",
            "id": "<string>",
            "amount_type": "<string>",
            "price_currency": "<string>",
            "is_archived": true,
            "product_id": "<string>",
            "type": "<string>",
            "price_amount": 123,
            "legacy": true
          }
        ],
        "benefits": [
          {
            "id": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "modified_at": "2023-11-07T05:31:56Z",
            "type": "<string>",
            "description": "<string>",
            "selectable": true,
            "deletable": true,
            "is_deleted": true,
            "organization_id": "<string>",
            "metadata": {},
            "properties": {
              "note": "<string>"
            },
            "visibility_configurable": true
          }
        ],
        "medias": [
          {
            "id": "<string>",
            "organization_id": "<string>",
            "name": "<string>",
            "path": "<string>",
            "mime_type": "<string>",
            "size": 123,
            "storage_version": "<string>",
            "checksum_etag": "<string>",
            "checksum_sha256_base64": "<string>",
            "checksum_sha256_hex": "<string>",
            "last_modified_at": "2023-11-07T05:31:56Z",
            "version": "<string>",
            "service": "<string>",
            "is_uploaded": true,
            "created_at": "2023-11-07T05:31:56Z",
            "size_readable": "<string>",
            "public_url": "<string>"
          }
        ],
        "attached_custom_fields": [
          {
            "custom_field_id": "<string>",
            "custom_field": {
              "created_at": "2023-11-07T05:31:56Z",
              "modified_at": "2023-11-07T05:31:56Z",
              "id": "<string>",
              "metadata": {},
              "type": "<string>",
              "slug": "<string>",
              "name": "<string>",
              "organization_id": "<string>",
              "properties": {
                "form_label": "<string>",
                "form_help_text": "<string>",
                "form_placeholder": "<string>",
                "textarea": true,
                "min_length": 1073741823,
                "max_length": 1073741823
              }
            },
            "order": 123,
            "required": true
          }
        ]
      },
      "discount": {
        "amount": 123,
        "currency": "<string>",
        "amounts": {},
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "id": "<string>",
        "metadata": {},
        "name": "<string>",
        "code": "<string>",
        "starts_at": "2023-11-07T05:31:56Z",
        "ends_at": "2023-11-07T05:31:56Z",
        "max_redemptions": 123,
        "redemptions_count": 123,
        "organization_id": "<string>"
      },
      "prices": [
        {
          "created_at": "2023-11-07T05:31:56Z",
          "modified_at": "2023-11-07T05:31:56Z",
          "id": "<string>",
          "amount_type": "<string>",
          "price_currency": "<string>",
          "is_archived": true,
          "product_id": "<string>",
          "type": "<string>",
          "price_amount": 123,
          "legacy": true
        }
      ],
      "meters": [
        {
          "created_at": "2023-11-07T05:31:56Z",
          "modified_at": "2023-11-07T05:31:56Z",
          "id": "<string>",
          "consumed_units": 123,
          "credited_units": 123,
          "amount": 123,
          "meter_id": "<string>",
          "meter": {
            "metadata": {},
            "created_at": "2023-11-07T05:31:56Z",
            "modified_at": "2023-11-07T05:31:56Z",
            "id": "<string>",
            "name": "<string>",
            "filter": {
              "clauses": [
                {
                  "property": "<string>",
                  "value": "<string>"
                }
              ]
            },
            "aggregation": {
              "func": "count"
            },
            "organization_id": "<string>",
            "custom_label": "<string>",
            "custom_multiplier": 123,
            "archived_at": "2023-11-07T05:31:56Z"
          }
        }
      ],
      "pending_update": {
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "id": "<string>",
        "applies_at": "2023-11-07T05:31:56Z",
        "product_id": "<string>",
        "seats": 123
      },
      "past_due_at": "2023-11-07T05:31:56Z",
      "seats": 123,
      "custom_field_data": {}
    }
  ],
  "pagination": {
    "total_count": 123,
    "max_page": 123
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

Authentication: You can generate a Personal Access Token from your settings.

Query Parameters

organization_id

Return only records matching organization ID. Identifier of the organization.

Example:

"1dbfc517-0bbf-4301-9ba8-555ca42b9737"

product_id

Return only records matching product ID. Identifier of the product.

customer_id

Return only records matching customer ID. Identifier of the customer.

external_customer_id

Return only records matching customer external ID. Identifier of the customer external.

discount_id

Return only records matching discount ID. Identifier of the product.

active

boolean | null

deprecated

Return only records matching active or inactive subscription.

status

Return only records matching subscription status.

Available options:

incomplete,

incomplete_expired,

trialing,

active,

past_due,

canceled,

unpaid

cancel_at_period_end

boolean | null

Return only records matching subscriptions that are set to cancel at period end.

customer_cancellation_reason

Return only records matching customer cancellation reason.

Available options:

customer_service,

low_quality,

missing_features,

switched_service,

too_complex,

too_expensive,

unused,

other

canceled_at_after

string<date-time> | null

Return only records matching cancellation date (after or equal to).

canceled_at_before

string<date-time> | null

Return only records matching cancellation date (before or equal to).

page

integer

default:1

Results page to return. The first page is used by default.

limit

integer

default:10

Records returned per page. Defaults to 10 and accepts up to 100.

sorting

enum<string>[] | null

Sort rules applied from left to right. Prefix any rule with - to reverse it into descending order.

Available options:

customer,

-customer,

status,

-status,

started_at,

-started_at,

current_period_end,

-current_period_end,

ended_at,

-ended_at,

ends_at,

-ends_at,

amount,

-amount,

product,

-product,

discount,

-discount

metadata

MetadataQuery · object | null

Return only records matching metadata key-value pairs. It uses the deepObject style, e.g. ?metadata[key]=value.

Show child attributes

Response

Request completed successfully

items

Subscription · object[]

required

Show child attributes

pagination

Pagination · object

required

Show child attributes

Create Subscription### Intent Creates a subscription from the values supplied in the request. ### When to call it Call this when your application has collected the required values and is ready to create a subscription. ### Access boundary Authorize the request with a token that carries `subscriptions:write`. ### Successful result A successful request returns `201`. The response schema below defines the body your integration receives. ### Operational notes This endpoint only allows to create subscription on free products. For paid products, use the checkout flow. No initial order will be created and no confirmation email will be sent.

⌘I

List Subscriptions

curl --request GET \
  --url https://api.getruba.com/v1/subscriptions/ \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.getruba.com/v1/subscriptions/"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.getruba.com/v1/subscriptions/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getruba.com/v1/subscriptions/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getruba.com/v1/subscriptions/"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.getruba.com/v1/subscriptions/")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getruba.com/v1/subscriptions/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "amount": 123,
      "currency": "<string>",
      "recurring_interval_count": 123,
      "current_period_start": "2023-11-07T05:31:56Z",
      "current_period_end": "2023-11-07T05:31:56Z",
      "trial_start": "2023-11-07T05:31:56Z",
      "trial_end": "2023-11-07T05:31:56Z",
      "cancel_at_period_end": true,
      "canceled_at": "2023-11-07T05:31:56Z",
      "started_at": "2023-11-07T05:31:56Z",
      "ends_at": "2023-11-07T05:31:56Z",
      "ended_at": "2023-11-07T05:31:56Z",
      "customer_id": "<string>",
      "product_id": "<string>",
      "discount_id": "<string>",
      "checkout_id": "<string>",
      "customer_cancellation_comment": "<string>",
      "metadata": {},
      "customer": {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "metadata": {},
        "email_verified": true,
        "name": "John Doe",
        "billing_name": "John Doe",
        "billing_address": {
          "line1": "<string>",
          "line2": "<string>",
          "postal_code": "<string>",
          "city": "<string>",
          "state": "<string>"
        },
        "tax_id": {
          "[0]": "<string>"
        },
        "organization_id": "<string>",
        "deleted_at": "2023-11-07T05:31:56Z",
        "avatar_url": "https://www.gravatar.com/avatar/xxx?d=404",
        "external_id": "usr_1337",
        "email": "customer@example.com",
        "locale": "<string>",
        "default_payment_method_id": "<string>"
      },
      "product": {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "trial_interval_count": 123,
        "name": "<string>",
        "description": "<string>",
        "recurring_interval_count": 123,
        "is_recurring": true,
        "is_archived": true,
        "organization_id": "<string>",
        "metadata": {},
        "prices": [
          {
            "created_at": "2023-11-07T05:31:56Z",
            "modified_at": "2023-11-07T05:31:56Z",
            "id": "<string>",
            "amount_type": "<string>",
            "price_currency": "<string>",
            "is_archived": true,
            "product_id": "<string>",
            "type": "<string>",
            "price_amount": 123,
            "legacy": true
          }
        ],
        "benefits": [
          {
            "id": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "modified_at": "2023-11-07T05:31:56Z",
            "type": "<string>",
            "description": "<string>",
            "selectable": true,
            "deletable": true,
            "is_deleted": true,
            "organization_id": "<string>",
            "metadata": {},
            "properties": {
              "note": "<string>"
            },
            "visibility_configurable": true
          }
        ],
        "medias": [
          {
            "id": "<string>",
            "organization_id": "<string>",
            "name": "<string>",
            "path": "<string>",
            "mime_type": "<string>",
            "size": 123,
            "storage_version": "<string>",
            "checksum_etag": "<string>",
            "checksum_sha256_base64": "<string>",
            "checksum_sha256_hex": "<string>",
            "last_modified_at": "2023-11-07T05:31:56Z",
            "version": "<string>",
            "service": "<string>",
            "is_uploaded": true,
            "created_at": "2023-11-07T05:31:56Z",
            "size_readable": "<string>",
            "public_url": "<string>"
          }
        ],
        "attached_custom_fields": [
          {
            "custom_field_id": "<string>",
            "custom_field": {
              "created_at": "2023-11-07T05:31:56Z",
              "modified_at": "2023-11-07T05:31:56Z",
              "id": "<string>",
              "metadata": {},
              "type": "<string>",
              "slug": "<string>",
              "name": "<string>",
              "organization_id": "<string>",
              "properties": {
                "form_label": "<string>",
                "form_help_text": "<string>",
                "form_placeholder": "<string>",
                "textarea": true,
                "min_length": 1073741823,
                "max_length": 1073741823
              }
            },
            "order": 123,
            "required": true
          }
        ]
      },
      "discount": {
        "amount": 123,
        "currency": "<string>",
        "amounts": {},
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "id": "<string>",
        "metadata": {},
        "name": "<string>",
        "code": "<string>",
        "starts_at": "2023-11-07T05:31:56Z",
        "ends_at": "2023-11-07T05:31:56Z",
        "max_redemptions": 123,
        "redemptions_count": 123,
        "organization_id": "<string>"
      },
      "prices": [
        {
          "created_at": "2023-11-07T05:31:56Z",
          "modified_at": "2023-11-07T05:31:56Z",
          "id": "<string>",
          "amount_type": "<string>",
          "price_currency": "<string>",
          "is_archived": true,
          "product_id": "<string>",
          "type": "<string>",
          "price_amount": 123,
          "legacy": true
        }
      ],
      "meters": [
        {
          "created_at": "2023-11-07T05:31:56Z",
          "modified_at": "2023-11-07T05:31:56Z",
          "id": "<string>",
          "consumed_units": 123,
          "credited_units": 123,
          "amount": 123,
          "meter_id": "<string>",
          "meter": {
            "metadata": {},
            "created_at": "2023-11-07T05:31:56Z",
            "modified_at": "2023-11-07T05:31:56Z",
            "id": "<string>",
            "name": "<string>",
            "filter": {
              "clauses": [
                {
                  "property": "<string>",
                  "value": "<string>"
                }
              ]
            },
            "aggregation": {
              "func": "count"
            },
            "organization_id": "<string>",
            "custom_label": "<string>",
            "custom_multiplier": 123,
            "archived_at": "2023-11-07T05:31:56Z"
          }
        }
      ],
      "pending_update": {
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "id": "<string>",
        "applies_at": "2023-11-07T05:31:56Z",
        "product_id": "<string>",
        "seats": 123
      },
      "past_due_at": "2023-11-07T05:31:56Z",
      "seats": 123,
      "custom_field_data": {}
    }
  ],
  "pagination": {
    "total_count": 123,
    "max_page": 123
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Read This First

Create a Sale

Collect and Reconcile

Manage Recurring Revenue

Model Customer Access

Power the Customer Portal

Configure the Platform

React to State Changes

List Subscriptions

Intent

When to call it

Access boundary

Successful result

Authorizations

Query Parameters

Response