Get Subscription
curl --request GET \
--url https://api.payviox.com/subscriptions/{subscription_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.payviox.com/subscriptions/{subscription_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.payviox.com/subscriptions/{subscription_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.payviox.com/subscriptions/{subscription_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.payviox.com/subscriptions/{subscription_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.payviox.com/subscriptions/{subscription_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.payviox.com/subscriptions/{subscription_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": "psub_8fKx2LmQp4ZrT7vW1nYc3aBd",
"status": "active",
"amount": 999,
"unit_amount": 1029,
"currency": "USD",
"interval": "month",
"interval_count": 1,
"interval_label": "every month",
"customer": "customer_abc123",
"customer_email": "john@example.com",
"order_id": "order_12345",
"items": [
{ "name": "Pro plan", "quantity": 1, "price": 999 }
],
"metadata": { "user_id": "usr_123" },
"payment_method": "credit",
"provider": "stripe",
"provider_subscription_id": "sub_1QxYz2AbCdEfGhIj",
"cycles_count": 2,
"current_period_end": "2026-12-13T10:30:00+00:00",
"cancel_at_period_end": false,
"canceled_at": null,
"canceled_by": null,
"cancel_requested_by": null,
"cancellation_reason": null,
"initial_session_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"management_url": "https://secure.payviox.com/subscription/k3Jd9QwL2xVb7NmP4tRz8YcF1sHg6UaE5oWi0qXn3BvM7ZpD",
"created_at": "2026-10-13T10:30:00+00:00"
}
{
"id": "psub_8fKx2LmQp4ZrT7vW1nYc3aBd",
"status": "canceled",
"amount": 999,
"unit_amount": 1029,
"currency": "USD",
"interval": "month",
"interval_count": 1,
"interval_label": "every month",
"customer": "customer_abc123",
"customer_email": "john@example.com",
"order_id": "order_12345",
"items": [
{ "name": "Pro plan", "quantity": 1, "price": 999 }
],
"metadata": { "user_id": "usr_123" },
"payment_method": "credit",
"provider": "stripe",
"provider_subscription_id": "sub_1QxYz2AbCdEfGhIj",
"cycles_count": 3,
"current_period_end": "2027-01-13T10:30:00+00:00",
"cancel_at_period_end": true,
"canceled_at": "2027-01-13T10:30:04+00:00",
"canceled_by": "payer",
"cancel_requested_by": "payer",
"cancellation_reason": "requested_by_customer",
"initial_session_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"management_url": "https://secure.payviox.com/subscription/k3Jd9QwL2xVb7NmP4tRz8YcF1sHg6UaE5oWi0qXn3BvM7ZpD",
"created_at": "2026-10-13T10:30:00+00:00"
}
{
"error": "subscription_not_found",
"message": "No subscription with this id on your account."
}
{
"error": "Unauthorized"
}
API - Endpoints
Get Subscription
Retrieve one subscription by its psub_ ID with the secret key: status (active, past_due, canceled), price per period (amount, unit_amount), interval, current_period_end, cancel_at_period_end, cancellation details, Stripe subscription ID and the customer management_url. Defines the Subscription object
GET
/
subscriptions
/
{subscription_id}
Get Subscription
curl --request GET \
--url https://api.payviox.com/subscriptions/{subscription_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.payviox.com/subscriptions/{subscription_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.payviox.com/subscriptions/{subscription_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.payviox.com/subscriptions/{subscription_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.payviox.com/subscriptions/{subscription_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.payviox.com/subscriptions/{subscription_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.payviox.com/subscriptions/{subscription_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": "psub_8fKx2LmQp4ZrT7vW1nYc3aBd",
"status": "active",
"amount": 999,
"unit_amount": 1029,
"currency": "USD",
"interval": "month",
"interval_count": 1,
"interval_label": "every month",
"customer": "customer_abc123",
"customer_email": "john@example.com",
"order_id": "order_12345",
"items": [
{ "name": "Pro plan", "quantity": 1, "price": 999 }
],
"metadata": { "user_id": "usr_123" },
"payment_method": "credit",
"provider": "stripe",
"provider_subscription_id": "sub_1QxYz2AbCdEfGhIj",
"cycles_count": 2,
"current_period_end": "2026-12-13T10:30:00+00:00",
"cancel_at_period_end": false,
"canceled_at": null,
"canceled_by": null,
"cancel_requested_by": null,
"cancellation_reason": null,
"initial_session_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"management_url": "https://secure.payviox.com/subscription/k3Jd9QwL2xVb7NmP4tRz8YcF1sHg6UaE5oWi0qXn3BvM7ZpD",
"created_at": "2026-10-13T10:30:00+00:00"
}
{
"id": "psub_8fKx2LmQp4ZrT7vW1nYc3aBd",
"status": "canceled",
"amount": 999,
"unit_amount": 1029,
"currency": "USD",
"interval": "month",
"interval_count": 1,
"interval_label": "every month",
"customer": "customer_abc123",
"customer_email": "john@example.com",
"order_id": "order_12345",
"items": [
{ "name": "Pro plan", "quantity": 1, "price": 999 }
],
"metadata": { "user_id": "usr_123" },
"payment_method": "credit",
"provider": "stripe",
"provider_subscription_id": "sub_1QxYz2AbCdEfGhIj",
"cycles_count": 3,
"current_period_end": "2027-01-13T10:30:00+00:00",
"cancel_at_period_end": true,
"canceled_at": "2027-01-13T10:30:04+00:00",
"canceled_by": "payer",
"cancel_requested_by": "payer",
"cancellation_reason": "requested_by_customer",
"initial_session_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"management_url": "https://secure.payviox.com/subscription/k3Jd9QwL2xVb7NmP4tRz8YcF1sHg6UaE5oWi0qXn3BvM7ZpD",
"created_at": "2026-10-13T10:30:00+00:00"
}
{
"error": "subscription_not_found",
"message": "No subscription with this id on your account."
}
{
"error": "Unauthorized"
}
Overview
Returns a subscription and its current state. Use it to check whether a customer’s subscription is still running, when it renews, or whether a cancellation is scheduled.All amounts are in cents (e.g.,
999 = $9.99). Dates are ISO 8601 strings.Authentication
This endpoint requires your Secret API Key (server-side only). See Authentication for details.Authorization: Bearer sk_live_xxxxxxxxxxxx
Never expose your Secret API Key in client-side code. This endpoint should only be called from your backend server.
Path Parameters
string
required
The Payviox subscription ID (
psub_...), as received in the subscription.id field of your webhooks.The Subscription object
string
required
Payviox subscription ID, prefixed with
psub_.string
required
active: paid up, renews automatically. A subscription with a scheduled cancellation staysactiveuntil it ends — checkcancel_at_period_end.past_due: the last renewal charge failed and Stripe is retrying it.canceled: ended. No further charges.
integer
required
Your price per period, in cents — the
amount of the signup session.integer
required
Amount charged to the customer at each renewal, in cents, fixed at signup. It includes the fees added for the customer at checkout, but not one-time add-on fees (such as fraud screening) charged on the first payment only — so it can be lower than what the customer paid at signup.
string
required
Always
USD.string
required
day, week, month or year.integer
required
Number of intervals between two charges.
string
required
Human-readable period, e.g.
every month or every 3 months.string
Customer identifier, as passed when creating the signup session.
string
Customer email — the
email passed when creating the signup session, or the one entered at checkout. Can be null.string
required
order_id of the signup session. Renewal payments use {order_id}-{cycle} (e.g. order_12345-2).array
Items of the signup session (one period).
object
Custom metadata of the signup session. It’s also sent with every renewal webhook.
string
Method the customer subscribed with:
credit, apple_pay or google_pay.string
Provider that charges the renewals:
stripe.string
ID of the subscription on your Stripe account (
sub_...). null until Payviox has created it, usually within a minute of the first payment.integer
required
Billing cycles started so far, signup included:
1 after signup, 2 after the first renewal, and so on. A renewal whose charge failed counts too.string
End of the current billing period: when the next renewal is charged, or when a scheduled cancellation takes effect.
boolean
required
true when the subscription is scheduled to end at current_period_end (by you or by the customer). See cancel_requested_by for who can undo it.string
When the subscription ended.
null while it isn’t canceled.string
Who ended it, once
status is canceled (null before):
api (your backend), manager (your dashboard), admin (Payviox support), payer (the customer, from the management link), provider (on Stripe — after all renewal retries failed, or canceled from your Stripe dashboard), system (Payviox — the signup payment was refunded, or the subscription couldn’t be created on Stripe: setup_failed).string
Who scheduled the end-of-period cancellation:
payer (the customer, from the management link), api (your backend), manager (your dashboard), admin (Payviox support) or system. null when no cancellation is scheduled — or when it was scheduled from your Stripe dashboard.Only the same side can undo it: you can resume api, manager and null; a payer cancellation can only be undone by the customer, and an admin/system one only by Payviox.string
Set as soon as a cancellation is requested or scheduled:
requested_by_merchant— you, from the API or the dashboardrequested_by_customer— the customer, from the management linkinitial_payment_refunded— the signup payment was refundedadmin— canceled by Payviox supportsetup_failed:<code>— Payviox couldn’t create the subscription on Stripe after the first payment- a Stripe reason, when it ended on Stripe’s side:
payment_failed(Stripe stopped retrying),cancellation_requested(canceled from your Stripe dashboard),provider,provider_deleted
string
required
Session ID of the signup payment.
string
Self-service page where the customer can see the subscription, cancel it at the end of the paid period, and undo that cancellation. Share it with your customer, for example in your confirmation email.
string
required
When the subscription was created (after the first payment succeeded).
Example Requests
curl https://api.payviox.com/subscriptions/psub_8fKx2LmQp4ZrT7vW1nYc3aBd \
-H "Authorization: Bearer sk_live_xxxxxxxxxxxx"
const response = await fetch(
'https://api.payviox.com/subscriptions/psub_8fKx2LmQp4ZrT7vW1nYc3aBd',
{ headers: { Authorization: `Bearer ${process.env.PAYVIOX_SECRET_KEY}` } }
);
const subscription = await response.json();
console.log(subscription.status); // "active"
console.log(subscription.current_period_end); // "2026-12-13T10:30:00+00:00"
import os
import requests
response = requests.get(
'https://api.payviox.com/subscriptions/psub_8fKx2LmQp4ZrT7vW1nYc3aBd',
headers={'Authorization': f"Bearer {os.environ['PAYVIOX_SECRET_KEY']}"}
)
subscription = response.json()
print(subscription['status']) # "active"
<?php
$ch = curl_init('https://api.payviox.com/subscriptions/psub_8fKx2LmQp4ZrT7vW1nYc3aBd');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer ' . getenv('PAYVIOX_SECRET_KEY')
]);
$subscription = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $subscription['status']; // "active"
Example Response
{
"id": "psub_8fKx2LmQp4ZrT7vW1nYc3aBd",
"status": "active",
"amount": 999,
"unit_amount": 1029,
"currency": "USD",
"interval": "month",
"interval_count": 1,
"interval_label": "every month",
"customer": "customer_abc123",
"customer_email": "john@example.com",
"order_id": "order_12345",
"items": [
{ "name": "Pro plan", "quantity": 1, "price": 999 }
],
"metadata": { "user_id": "usr_123" },
"payment_method": "credit",
"provider": "stripe",
"provider_subscription_id": "sub_1QxYz2AbCdEfGhIj",
"cycles_count": 2,
"current_period_end": "2026-12-13T10:30:00+00:00",
"cancel_at_period_end": false,
"canceled_at": null,
"canceled_by": null,
"cancel_requested_by": null,
"cancellation_reason": null,
"initial_session_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"management_url": "https://secure.payviox.com/subscription/k3Jd9QwL2xVb7NmP4tRz8YcF1sHg6UaE5oWi0qXn3BvM7ZpD",
"created_at": "2026-10-13T10:30:00+00:00"
}
{
"id": "psub_8fKx2LmQp4ZrT7vW1nYc3aBd",
"status": "canceled",
"amount": 999,
"unit_amount": 1029,
"currency": "USD",
"interval": "month",
"interval_count": 1,
"interval_label": "every month",
"customer": "customer_abc123",
"customer_email": "john@example.com",
"order_id": "order_12345",
"items": [
{ "name": "Pro plan", "quantity": 1, "price": 999 }
],
"metadata": { "user_id": "usr_123" },
"payment_method": "credit",
"provider": "stripe",
"provider_subscription_id": "sub_1QxYz2AbCdEfGhIj",
"cycles_count": 3,
"current_period_end": "2027-01-13T10:30:00+00:00",
"cancel_at_period_end": true,
"canceled_at": "2027-01-13T10:30:04+00:00",
"canceled_by": "payer",
"cancel_requested_by": "payer",
"cancellation_reason": "requested_by_customer",
"initial_session_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"management_url": "https://secure.payviox.com/subscription/k3Jd9QwL2xVb7NmP4tRz8YcF1sHg6UaE5oWi0qXn3BvM7ZpD",
"created_at": "2026-10-13T10:30:00+00:00"
}
{
"error": "subscription_not_found",
"message": "No subscription with this id on your account."
}
{
"error": "Unauthorized"
}
Error Responses
401 -- Unauthorized
401 -- Unauthorized
The API key is missing or invalid. This endpoint only accepts your Secret API Key.
404 -- Subscription not found
404 -- Subscription not found
No subscription with this ID belongs to your business. Subscriptions of other businesses are reported as not found too.
Related
Subscriptions guide
End-to-end flow: Stripe setup, signup, renewals, cancellation
List Subscriptions
Filter by status or customer, paginate
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Payviox subscription ID (psub_...)
Response
Subscription retrieved successfully
Payviox subscription ID (psub_ prefix)
active: paid up, renews automatically (also while a cancellation is scheduled, see cancel_at_period_end). past_due: the last renewal charge failed and Stripe is retrying it. canceled: ended, no further charges.
Available options:
active, past_due, canceled Your price per period in cents — the amount of the signup session
Amount charged to the customer at each renewal, in cents. Includes the fees added for the customer at checkout, but not one-time add-on fees (such as fraud screening) charged on the first payment only, so it can be lower than the first charge.
Always USD
Available options:
day, week, month, year Human-readable period, e.g. every month, every 3 months
order_id of the signup session. Renewals use {order_id}-{cycle}
Billing cycles started so far, signup included (1 = signup only). A renewal whose charge failed counts too.
true when the subscription is scheduled to end at current_period_end
Session ID of the signup payment
Customer identifier from the signup session
Customer email, from the signup session or entered at checkout
Items of the signup session (one period)
Metadata of the signup session
Method the customer subscribed with (read with provider)
Available options:
credit, apple_pay, google_pay Provider that charges the renewals (stripe)
ID of the subscription on your Stripe account (sub_...). null until Payviox has created it, usually within a minute of the first payment.
End of the current billing period: date of the next renewal charge, or the date a scheduled cancellation takes effect
When the subscription ended (null while not canceled)
Who ended it: api (your backend), manager (your dashboard), admin (Payviox support), payer (the customer, from the management link), provider (on Stripe, e.g. after failed retries or a cancellation in the Stripe dashboard), system (Payviox, e.g. signup payment refunded or setup_failed). null until the subscription is canceled.
Available options:
api, manager, admin, payer, provider, system, null Who scheduled the end-of-period cancellation: payer (the customer), api, manager (your dashboard), admin (Payviox support) or system. null when no cancellation is scheduled, or when it was scheduled from your Stripe dashboard. Only the same side can resume it: you (api, manager, null), the customer (payer) or Payviox (admin, system).
Available options:
payer, api, manager, admin, system, null Set as soon as a cancellation is requested or scheduled: requested_by_merchant, requested_by_customer, initial_payment_refunded, admin (canceled by Payviox support), setup_failed:<code>, or a Stripe reason such as payment_failed, cancellation_requested, provider or provider_deleted. Treat unknown values as informational.
Customer self-service page (view, cancel at period end, undo). Share it with your customer, e.g. in your confirmation email.