Retrieve a subscription
curl --request GET \
--url https://api.saasybill.com/v1/subscriptions/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.saasybill.com/v1/subscriptions/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.saasybill.com/v1/subscriptions/{id}', 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.saasybill.com/v1/subscriptions/{id}",
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.saasybill.com/v1/subscriptions/{id}"
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.saasybill.com/v1/subscriptions/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.saasybill.com/v1/subscriptions/{id}")
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{
"id": "9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33",
"object": "subscription",
"customer": "3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11",
"customer_code": "ACME-001",
"plan": "b6c1e0a4-2f7d-4a61-8f0c-5d3e9a7b2c44",
"status": "active",
"currency": "AUD",
"interval": {
"unit": "month",
"count": 1
},
"timezone": "Australia/Sydney",
"start_date": "2026-09-30",
"renewal_date": "2026-10-30",
"end_date": null,
"units": 10,
"minimum_units": 5,
"discount_percent": "10.00",
"cancel_at_period_end": false,
"end_after_cycles": null,
"label": "Acme � Team plan",
"invoice_reference": "PO-4471",
"renewal_value": "108.0000",
"usage_value": "0.0000",
"usage_value_annual": "0.0000",
"minimum_usage_value": "0.0000",
"meters": [],
"cpi_enabled": false,
"created": "2026-09-30T04:12:00.000Z"
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "Provide a valid API key as `Authorization: Bearer <key>`.",
"request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
}
}{
"error": {
"type": "permission_error",
"code": "insufficient_scope",
"message": "This API key does not have the `subscriptions:write` scope.",
"request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
}
}{
"error": {
"type": "not_found",
"code": "subscription_not_found",
"message": "There is no subscription with that id.",
"request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
}
}{
"error": {
"type": "conflict",
"code": "idempotency_conflict",
"message": "This `Idempotency-Key` was used with a different request. Use a new key for a different request.",
"request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
}
}{
"error": {
"type": "invalid_request_error",
"code": "invalid_parameter",
"message": "`units`: Invalid input: expected number, received string",
"param": "units",
"request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
}
}{
"error": {
"type": "rate_limit_error",
"code": "rate_limited",
"message": "Too many requests. Try again in 12 seconds.",
"request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
}
}{
"error": {
"type": "api_error",
"code": "internal_error",
"message": "Something went wrong on our side. Retry the request; if it keeps failing, quote the request id.",
"request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
}
}Subscriptions
Retrieve a subscription
GET
/
v1
/
subscriptions
/
{id}
Retrieve a subscription
curl --request GET \
--url https://api.saasybill.com/v1/subscriptions/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.saasybill.com/v1/subscriptions/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.saasybill.com/v1/subscriptions/{id}', 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.saasybill.com/v1/subscriptions/{id}",
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.saasybill.com/v1/subscriptions/{id}"
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.saasybill.com/v1/subscriptions/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.saasybill.com/v1/subscriptions/{id}")
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{
"id": "9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33",
"object": "subscription",
"customer": "3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11",
"customer_code": "ACME-001",
"plan": "b6c1e0a4-2f7d-4a61-8f0c-5d3e9a7b2c44",
"status": "active",
"currency": "AUD",
"interval": {
"unit": "month",
"count": 1
},
"timezone": "Australia/Sydney",
"start_date": "2026-09-30",
"renewal_date": "2026-10-30",
"end_date": null,
"units": 10,
"minimum_units": 5,
"discount_percent": "10.00",
"cancel_at_period_end": false,
"end_after_cycles": null,
"label": "Acme � Team plan",
"invoice_reference": "PO-4471",
"renewal_value": "108.0000",
"usage_value": "0.0000",
"usage_value_annual": "0.0000",
"minimum_usage_value": "0.0000",
"meters": [],
"cpi_enabled": false,
"created": "2026-09-30T04:12:00.000Z"
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "Provide a valid API key as `Authorization: Bearer <key>`.",
"request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
}
}{
"error": {
"type": "permission_error",
"code": "insufficient_scope",
"message": "This API key does not have the `subscriptions:write` scope.",
"request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
}
}{
"error": {
"type": "not_found",
"code": "subscription_not_found",
"message": "There is no subscription with that id.",
"request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
}
}{
"error": {
"type": "conflict",
"code": "idempotency_conflict",
"message": "This `Idempotency-Key` was used with a different request. Use a new key for a different request.",
"request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
}
}{
"error": {
"type": "invalid_request_error",
"code": "invalid_parameter",
"message": "`units`: Invalid input: expected number, received string",
"param": "units",
"request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
}
}{
"error": {
"type": "rate_limit_error",
"code": "rate_limited",
"message": "Too many requests. Try again in 12 seconds.",
"request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
}
}{
"error": {
"type": "api_error",
"code": "internal_error",
"message": "Something went wrong on our side. Retry the request; if it keeps failing, quote the request id.",
"request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
}
}Requires the
subscriptions:read scope. See Authentication.Authorizations
An API key. Its scopes decide what it may call: customers:read (List and look up customers.) customers:write (Create customers, and Xero contacts where the organisation allows it.) catalogue:read (List plans and charges.) subscriptions:read (List and look up subscriptions.) subscriptions:write (Create subscriptions, change units, end and restore them.) invoices:read (List and look up invoices.) credit_notes:read (List and look up credit notes, and where their credit was applied.)
Path Parameters
The Saasybill id of the subscription.
Example:
"9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33"
Response
Success.
Allowed value:
"subscription"Available options:
pending, active, complete, ended Show child attributes
Show child attributes
YYYY-MM-DD, in the subscription's own timezone.
YYYY-MM-DD, in the subscription's own timezone.
YYYY-MM-DD, in the subscription's own timezone.
A decimal string, e.g. "19.9900".
What the next period is certain to bill: the plan at its current units, the add-ons, and the minimum units of each meter the plan bills, net of the discount. Usage above the meter minimums is not included; see usage_value.
The average, over the last three closed usage periods, of what each billed for usage above the meter minimums, net of the discount. An estimate at the plan's current meter prices, and never part of renewal_value. 0 until a usage period has closed, and for a plan that bills no meter.
usage_value times the periods in a year.
The part of renewal_value that is the meter minimums, net of the discount. 0 for a plan that bills no meter.
The meters the subscription's plan bills for, with the minimum each is billed at.
Show child attributes
Show child attributes
Whether the price rises with CPI at each renewal.
ISO 8601, UTC.
Was this page helpful?