Subscriptions
List Subscriptions
Retrieve a list of subscriptions
GET
/
v1
/
subscriptions
List subscriptions
curl --request GET \
--url https://billing.example.com/v1/subscriptions \
--header 'Authorization: Bearer <token>'import requests
url = "https://billing.example.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://billing.example.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://billing.example.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://billing.example.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://billing.example.com/v1/subscriptions")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://billing.example.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{
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "trialing",
"current_period_start": "2023-11-07T05:31:56Z",
"current_period_end": "2023-11-07T05:31:56Z",
"cancel_at_period_end": true,
"canceled_at": "2023-11-07T05:31:56Z",
"cancellation_reason": "<string>",
"cancellation_feedback": "<string>",
"billing_anchor": "2023-11-07T05:31:56Z",
"billing_anchor_type": "<string>",
"billing_anchor_day": 123,
"payment_terms": "<string>",
"coupon_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference_id": "<string>",
"mandate_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"razorpay_subscription_id": "<string>",
"stripe_subscription_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
]
}{
"error": {
"code": "BAD_REQUEST",
"message": "<string>"
}
}Query Parameters
| Parameter | Type | Description |
|---|---|---|
status | string | Filter by status (active, trialing, paused, past_due, canceled) |
plan_id | string (uuid) | Filter to one plan’s subscriptions |
customer_id | string (uuid) | Filter to one customer’s subscriptions |
started_after | string (RFC 3339) | Keep subscriptions whose current period started at or after this instant |
q | string | Search by customer name, email, or subscription id |
limit | integer | Max results (default: 50, capped at 1000) |
page | integer | Page number (1-based) |
Example Request
curl "https://api.recurso.dev/v1/subscriptions?status=active&plan_id=8f14e45f-ceea-4e07-8c65-4c11a3f2fd60" \
-H "Authorization: Bearer $API_KEY"
Response
{
"object": "list",
"data": [
{
"id": "sub_xyz789",
"object": "subscription",
"customer_id": "cust_abc123",
"plan_id": "plan_pro",
"status": "active",
"current_period_end": "2024-02-15T00:00:00Z"
}
],
"has_more": false,
"total_count": 1
}
Authorizations
Tenant API key obtained from POST /auth/register or POST /v1/developer/keys.
Query Parameters
Filter by subscription status.
Available options:
trialing, active, past_due, paused, canceled, unpaid Filter to one plan's subscriptions.
Filter to one customer's subscriptions.
Keep subscriptions whose current period started at or after this RFC 3339 instant.
Free-text search filter.
Maximum records to return. Defaults to 50 when omitted and is capped at 1000 (a larger request returns the cap, not an error). Pass an explicit limit when you need the full set — omitting it silently returns only the first page.
Required range:
1 <= x <= 10001-based page number.
Required range:
x >= 1Response
Subscriptions for the tenant.
Show child attributes
Show child attributes
⌘I
List subscriptions
curl --request GET \
--url https://billing.example.com/v1/subscriptions \
--header 'Authorization: Bearer <token>'import requests
url = "https://billing.example.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://billing.example.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://billing.example.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://billing.example.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://billing.example.com/v1/subscriptions")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://billing.example.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{
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "trialing",
"current_period_start": "2023-11-07T05:31:56Z",
"current_period_end": "2023-11-07T05:31:56Z",
"cancel_at_period_end": true,
"canceled_at": "2023-11-07T05:31:56Z",
"cancellation_reason": "<string>",
"cancellation_feedback": "<string>",
"billing_anchor": "2023-11-07T05:31:56Z",
"billing_anchor_type": "<string>",
"billing_anchor_day": 123,
"payment_terms": "<string>",
"coupon_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference_id": "<string>",
"mandate_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"razorpay_subscription_id": "<string>",
"stripe_subscription_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
]
}{
"error": {
"code": "BAD_REQUEST",
"message": "<string>"
}
}