List all subscriptions

GET https://api.tamio.com/v2/subscriptions/list

Returns a paginated list of subscriptions. Supports filtering by customer, product, instalment plan, billing cycle, currency, status flags (cancelled, completed, paused, instalments), date range, and free-text search.

Query Parameters

page integer*

Page number for pagination.

per_page integer*

Number of subscriptions per page.

order string

Sort direction.

ascdesc

sort_by string

Field to sort by.

emailnext_billing_datestatusdatecancelledpayment_count

filter string

Free-text search across subscription data.

from string

Start date filter (ISO string or Unix timestamp).

to string

End date filter (ISO string or Unix timestamp).

customer_id string

Filter by customer UUID.

product_id string

Filter by product UUID.

instalment_plan_id string

Filter by instalment plan UUID.

cancelled boolean

Show only cancelled subscriptions.

completed boolean

Show only completed subscriptions.

exclude_paused boolean

Exclude paused subscriptions from results.

instalments boolean

Show only instalment-based subscriptions.

billing_cycle string

Filter by billing frequency.

dayweekmonthyear

currency string

Filter by ISO currency code.

Responses

200 Paginated list of subscriptions

Paginated list of subscriptions

status integer

total_results integer

Total number of subscriptions matching the filters.

subscriptions array of Subscription

id string

Unique identifier of the subscription.

object string

Object type identifier.

next_billing_date integer

Unix timestamp of the next billing date. Null if subscription is not active, trialing, or past_due.

cancellation_date integer

Unix timestamp when the subscription was cancelled. Null if not cancelled.

completion_date integer

Unix timestamp when the subscription completed (instalment plans only). Null if not completed.

resumes_at integer

Unix timestamp when a paused subscription will automatically resume. Null if not paused or no resume date set.

products array of object

Products included in the subscription with pricing details.

id string

Product UUID.

name string

Product name.

payment_count integer

Number of payments processed for this subscription.

status string

Current subscription status.

activetrialingpast_duepausedcancelledcompleted

has_discount boolean

Whether a promotional discount is currently applied.

gateway_subscription_id string

External payment gateway subscription identifier (e.g. Stripe subscription ID).

type string

Subscription type. subscription for recurring plans, instalment for payment plans, recurring_invoice for invoice-based billing.

subscriptioninstalmentrecurring_invoice

gateway string

Payment gateway used (e.g. stripe, gocardless, mollie).

billing_cycle string

Billing frequency.

dayweekmonthyear

interval integer

Billing interval count (e.g. 1 for monthly, 3 for quarterly when billing_cycle is month).

currency string

ISO currency code.

invoice_id string

UUID of the most recent invoice. Null if no invoices exist.

price integer

Subscription price in smallest currency unit (e.g. cents).

lifetime_revenue integer

Total revenue generated from this subscription in smallest currency unit.

management_link string

Customer-facing portal URL for subscription management.

instalments_count integer

Number of total instalments. 0 for regular subscriptions.

customer SubscriptionCustomer

imported boolean

Whether the subscription was imported from an external system.

has_notes boolean

Whether associated notes exist for this subscription.

401 Missing or invalid API key

Retrieve a subscription

/subscriptions/list

1 const response = await fetch("https://api.tamio.com/v2/subscriptions/list", {
2   headers: {
3     "Authorization": "Bearer YOUR_API_KEY",
4     "Accept": "application/json"
5   }
6 });
7 const data = await response.json();

1 require "uri"
2 require "net/http"
3 
4 url = URI("https://api.tamio.com/v2/subscriptions/list")
5 
6 https = Net::HTTP.new(url.host, url.port)
7 https.use_ssl = true
8 
9 request = Net::HTTP::Get.new(url)
10 request["Accept"] = "application/json"
11 request["Authorization"] = "Bearer YOUR_API_KEY"
12 
13 response = https.request(request)
14 puts response.read_body

Responses

{
  "status": 200,
  "total_results": 85,
  "subscriptions": [
    {
      "id": "999e4567-e89b-12d3-a456-426614174000",
      "object": "subscription",
      "next_billing_date": 1735689600,
      "cancellation_date": null,
      "completion_date": null,
      "resumes_at": null,
      "products": [
        {
          "id": "bbb24567-e89b-12d3-a456-426614174000",
          "name": "Pro Plan"
        }
      ],
      "payment_count": 12,
      "status": "active",
      "has_discount": false,
      "gateway_subscription_id": "sub_1PaBcDeFgHiJkLmN",
      "type": "subscription",
      "gateway": "stripe",
      "billing_cycle": "month",
      "interval": 1,
      "currency": "EUR",
      "invoice_id": "aaa14567-e89b-12d3-a456-426614174000",
      "price": 2990,
      "lifetime_revenue": 35880,
      "management_link": "https://billing.example.com",
      "instalments_count": 0,
      "customer": {
        "id": "ccc34567-e89b-12d3-a456-426614174000",
        "name": "John",
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "locale": "en",
        "client_id": null,
        "address_id": null
      },
      "imported": false,
      "has_notes": false
    }
  ]
}

1	const response = await fetch("https://api.tamio.com/v2/subscriptions/list", {
2	headers: {
3	"Authorization": "Bearer YOUR_API_KEY",
4	"Accept": "application/json"
5	}
6	});
7	const data = await response.json();

1	require "uri"
2	require "net/http"
3
4	url = URI("https://api.tamio.com/v2/subscriptions/list")
5
6	https = Net::HTTP.new(url.host, url.port)
7	https.use_ssl = true
8
9	request = Net::HTTP::Get.new(url)
10	request["Accept"] = "application/json"
11	request["Authorization"] = "Bearer YOUR_API_KEY"
12
13	response = https.request(request)
14	puts response.read_body