Retrieve Subscription

GET

subscriptions

{subscription_id}

curl --request GET \
  --url https://api-sandbox.y.uno/v1/subscriptions/{subscription_id} \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>'

import requests

url = "https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}"

headers = {
    "public-api-key": "<api-key>",
    "private-secret-key": "<api-key>"
}

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

print(response.text)

const options = {
  method: 'GET',
  headers: {'public-api-key': '<api-key>', 'private-secret-key': '<api-key>'}
};

fetch('https://api-sandbox.y.uno/v1/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-sandbox.y.uno/v1/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 => [
    "private-secret-key: <api-key>",
    "public-api-key: <api-key>"
  ],
]);

$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-sandbox.y.uno/v1/subscriptions/{subscription_id}"

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

	req.Header.Add("public-api-key", "<api-key>")
	req.Header.Add("private-secret-key", "<api-key>")

	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-sandbox.y.uno/v1/subscriptions/{subscription_id}")
  .header("public-api-key", "<api-key>")
  .header("private-secret-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}")

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

request = Net::HTTP::Get.new(url)
request["public-api-key"] = '<api-key>'
request["private-secret-key"] = '<api-key>'

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

{
  "id": "7304911d-5df9-429e-8488-ad41abea1a4c",
  "name": "sub_001",
  "description": "streaming service",
  "account_id": "2404911d-5df9-429e-8488-ad41abea1a4b",
  "country": "US",
  "merchant_reference": "001_marzo_23",
  "soft_descriptor": "ACME SUBSCRIPTION",
  "status": "ACTIVE",
  "amount": {
    "currency": "USD",
    "value": 12100
  },
  "frequency": {
    "type": "MONTH",
    "value": 1
  },
  "billing_cycles": {
    "total": 10,
    "current": 2,
    "next_at": "2023-02-16T20:00:00.786342Z"
  },
  "current_period_start": "2023-01-16T20:00:00.912480Z",
  "current_period_end": "2023-02-16T20:00:00.786342Z",
  "billing_date": null,
  "customer_payer": {
    "id": "3t04911d-5df9-429e-8488-ad41abea1a2c"
  },
  "payment_method": {
    "type": "CARD",
    "vaulted_token": "6104911d-5df9-429e-8488-ad41abea1a4b",
    "card": {
      "installments": null,
      "network_transaction_id": null,
      "usage": "FIRST"
    }
  },
  "availability": {
    "start_at": "2024-01-16T00:00:00.786342Z",
    "finish_at": "2024-05-26T20:00:00.786342Z"
  },
  "retries": {
    "retry_on_decline": true,
    "amount": 4,
    "strategy": "DEFAULT",
    "schedule": null,
    "stop_on_hard_decline": null,
    "cancel_on_exhausted_retries": null
  },
  "trial_period": {
    "billing_cycles": 1,
    "amount": {
      "value": 0,
      "currency": ""
    }
  },
  "initial_payment_validation": false,
  "metadata": [
    {
      "key": "sub_ext_id",
      "value": "AA001"
    }
  ],
  "additional_data": null,
  "reason": null,
  "renewal_notification_days": 3,
  "payments": [
    "5104911d-5df9-229e-8468-bd41abea1a4s"
  ],
  "subscription_agreement_id": null,
  "cancellation_time": null,
  "cancellation_source": null,
  "ending_time": null,
  "plan_id": "00000000-0000-4000-8000-000000000001",
  "plan_assigned_at": "2023-12-16T20:46:54.786342Z",
  "previous_subscription_id": null,
  "phases": [
    {
      "order": 1,
      "name": "Intro",
      "type": "TRIAL",
      "duration": {
        "type": "MONTH",
        "value": 3
      },
      "frequency": {
        "type": "MONTH",
        "value": 1
      },
      "amount": {
        "currency": "USD",
        "value": 9.99
      },
      "total_payments": 3,
      "country_prices": []
    },
    {
      "order": 2,
      "name": "Regular",
      "type": "REGULAR",
      "duration": null,
      "frequency": null,
      "amount": null,
      "total_payments": null,
      "country_prices": []
    }
  ],
  "current_phase": "REGULAR",
  "billing_phases": [
    {
      "order": 1,
      "type": "TRIAL",
      "name": "Intro",
      "amount": {
        "currency": "USD",
        "value": 9.99
      },
      "frequency": {
        "type": "MONTH",
        "value": 1
      },
      "start_cycle": 0,
      "end_cycle": 2
    }
  ],
  "pending_plan_change": null,
  "created_at": "2023-12-16T20:46:54.786342Z",
  "updated_at": "2023-12-16T21:00:54.786342Z"
}

{
  "code": "SUBSCRIPTION_NOT_FOUND",
  "messages": [
    "Subscription not found."
  ]
}

Authorizations

public-api-key

string

header

default:<Your public-api-key>

required

private-secret-key

string

header

default:<Your private-secret-key>

required

Path Parameters

subscription_id

string

required

The unique identifier of the subscription.

Response

200

string

Example:

"7304911d-5df9-429e-8488-ad41abea1a4c"

name

string

Example:

"sub_001"

description

string

Example:

"streaming service"

account_id

string

Example:

"2404911d-5df9-429e-8488-ad41abea1a4b"

country

string

The subscription's country (ISO 3166-1 alpha-2).

Example:

"US"

merchant_reference

string

Example:

"001_marzo_23"

soft_descriptor

string

Example:

"ACME SUBSCRIPTION"

status

string

Example:

"ACTIVE"

amount

object

Show child attributes

frequency

object

Show child attributes

billing_cycles

object

Show child attributes

current_period_start

string

Only returned by this endpoint, and only once the first billing cycle has been charged. Always returned together with current_period_end.

Example:

"2023-01-16T20:00:00.912480Z"

current_period_end

string

Only returned by this endpoint, and only once the first billing cycle has been charged. Equal to billing_cycles.next_at. Always returned together with current_period_start.

Example:

"2023-02-16T20:00:00.786342Z"

billing_date

object | null

Only present on subscriptions billed on a fixed date instead of a frequency; mutually exclusive with frequency.

Show child attributes

customer_payer

object

Show child attributes

payment_method

object

Show child attributes

availability

object

Show child attributes

retries

object | null

The retry policy applied when a recurring charge is declined. See Retries.

Show child attributes

trial_period

object

Show child attributes

metadata

object[]

Show child attributes

additional_data

object | null

The optional order enrichment sent at creation, echoed back. See The Subscription Object for its full shape.

initial_payment_validation

boolean

Whether the subscription waited for its first payment to succeed before activating. false by default.

Example:

false

reason

string | null

Free-form reason for the subscription's current status, when one was recorded; null otherwise.

Example:

"merchant request"

renewal_notification_days

integer | null

How many days before the next billing date the subscription.close_to_renewal webhook is sent. null means no renewal notification is sent.

Example:

3

payments

string[]

subscription_agreement_id

string

Example:

"sa_6af2dfcd-44c0-4f16-a331-8bed3ed9c9fa"

cancellation_time

string | null

When the subscription was canceled. Only set once it reaches CANCELED; null otherwise.

Example:

"2023-12-16T20:46:54.786342Z"

cancellation_source

string | null

What triggered the cancellation: MERCHANT, SYSTEM, PLAN_CHANGE or RETRIES_EXHAUSTED. Only set once the subscription reaches CANCELED; null otherwise. Treat as open-ended — handle unrecognized values gracefully.

Example:

"MERCHANT"

ending_time

string | null

When the subscription completed or expired. Only set once it reaches COMPLETED; null otherwise.

Example:

"2024-12-16T20:46:54.786342Z"

plan_id

string

Only present when the subscription is linked to a plan.

Example:

"00000000-0000-4000-8000-000000000001"

plan_assigned_at

string

Only present on plan-linked subscriptions. The moment the plan was attached — at creation from a plan, migration onto a plan, or a plan change.

Example:

"2023-12-16T20:46:54.786342Z"

previous_subscription_id

string

Only present when this subscription was created by a plan change (switching an existing subscription to a different plan).

phases

object[]

The linked plan's phase definitions, as the plan declares them — including the terminal REGULAR phase. Only present on plan-linked subscriptions whose plan has phases. This is the plan's own ladder, not this subscriber's snapshot: for what was pinned for this subscription at creation, use billing_phases.

Show child attributes

current_phase

string

Only present on plan-linked subscriptions.

Example:

"REGULAR"

billing_phases

object[]

Only present on plan-linked subscriptions whose plan has phases. Contains the leading TRIAL phases only, snapshotted at creation — the terminal REGULAR phase is never included, since its price isn't pinned and instead resolves from the plan at every billing. current_phase: "REGULAR" is how you know the ladder is exhausted.

Show child attributes

pending_plan_change

object | null

The plan change scheduled for the next billing cycle, or null when none is pending. Schedule one with the plan_change block on Update Subscription.

Show child attributes

created_at

string

Example:

"2023-12-16T20:46:54.786342Z"

updated_at

string

Example:

"2023-12-16T21:00:54.786342Z"

Retrieve Subscription

curl --request GET \
  --url https://api-sandbox.y.uno/v1/subscriptions/{subscription_id} \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>'

import requests

url = "https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}"

headers = {
    "public-api-key": "<api-key>",
    "private-secret-key": "<api-key>"
}

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

print(response.text)

const options = {
  method: 'GET',
  headers: {'public-api-key': '<api-key>', 'private-secret-key': '<api-key>'}
};

fetch('https://api-sandbox.y.uno/v1/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-sandbox.y.uno/v1/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 => [
    "private-secret-key: <api-key>",
    "public-api-key: <api-key>"
  ],
]);

$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-sandbox.y.uno/v1/subscriptions/{subscription_id}"

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

	req.Header.Add("public-api-key", "<api-key>")
	req.Header.Add("private-secret-key", "<api-key>")

	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-sandbox.y.uno/v1/subscriptions/{subscription_id}")
  .header("public-api-key", "<api-key>")
  .header("private-secret-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}")

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

request = Net::HTTP::Get.new(url)
request["public-api-key"] = '<api-key>'
request["private-secret-key"] = '<api-key>'

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

{
  "id": "7304911d-5df9-429e-8488-ad41abea1a4c",
  "name": "sub_001",
  "description": "streaming service",
  "account_id": "2404911d-5df9-429e-8488-ad41abea1a4b",
  "country": "US",
  "merchant_reference": "001_marzo_23",
  "soft_descriptor": "ACME SUBSCRIPTION",
  "status": "ACTIVE",
  "amount": {
    "currency": "USD",
    "value": 12100
  },
  "frequency": {
    "type": "MONTH",
    "value": 1
  },
  "billing_cycles": {
    "total": 10,
    "current": 2,
    "next_at": "2023-02-16T20:00:00.786342Z"
  },
  "current_period_start": "2023-01-16T20:00:00.912480Z",
  "current_period_end": "2023-02-16T20:00:00.786342Z",
  "billing_date": null,
  "customer_payer": {
    "id": "3t04911d-5df9-429e-8488-ad41abea1a2c"
  },
  "payment_method": {
    "type": "CARD",
    "vaulted_token": "6104911d-5df9-429e-8488-ad41abea1a4b",
    "card": {
      "installments": null,
      "network_transaction_id": null,
      "usage": "FIRST"
    }
  },
  "availability": {
    "start_at": "2024-01-16T00:00:00.786342Z",
    "finish_at": "2024-05-26T20:00:00.786342Z"
  },
  "retries": {
    "retry_on_decline": true,
    "amount": 4,
    "strategy": "DEFAULT",
    "schedule": null,
    "stop_on_hard_decline": null,
    "cancel_on_exhausted_retries": null
  },
  "trial_period": {
    "billing_cycles": 1,
    "amount": {
      "value": 0,
      "currency": ""
    }
  },
  "initial_payment_validation": false,
  "metadata": [
    {
      "key": "sub_ext_id",
      "value": "AA001"
    }
  ],
  "additional_data": null,
  "reason": null,
  "renewal_notification_days": 3,
  "payments": [
    "5104911d-5df9-229e-8468-bd41abea1a4s"
  ],
  "subscription_agreement_id": null,
  "cancellation_time": null,
  "cancellation_source": null,
  "ending_time": null,
  "plan_id": "00000000-0000-4000-8000-000000000001",
  "plan_assigned_at": "2023-12-16T20:46:54.786342Z",
  "previous_subscription_id": null,
  "phases": [
    {
      "order": 1,
      "name": "Intro",
      "type": "TRIAL",
      "duration": {
        "type": "MONTH",
        "value": 3
      },
      "frequency": {
        "type": "MONTH",
        "value": 1
      },
      "amount": {
        "currency": "USD",
        "value": 9.99
      },
      "total_payments": 3,
      "country_prices": []
    },
    {
      "order": 2,
      "name": "Regular",
      "type": "REGULAR",
      "duration": null,
      "frequency": null,
      "amount": null,
      "total_payments": null,
      "country_prices": []
    }
  ],
  "current_phase": "REGULAR",
  "billing_phases": [
    {
      "order": 1,
      "type": "TRIAL",
      "name": "Intro",
      "amount": {
        "currency": "USD",
        "value": 9.99
      },
      "frequency": {
        "type": "MONTH",
        "value": 1
      },
      "start_cycle": 0,
      "end_cycle": 2
    }
  ],
  "pending_plan_change": null,
  "created_at": "2023-12-16T20:46:54.786342Z",
  "updated_at": "2023-12-16T21:00:54.786342Z"
}

{
  "code": "SUBSCRIPTION_NOT_FOUND",
  "messages": [
    "Subscription not found."
  ]
}

Getting Started

Reference

Customers

Network Tokens

Customer Sessions (Enrollment)

Checkout Sessions

Payment Methods (Checkout)

Checkout Builder

Payment Methods (Direct Workflow)

PCI Proxy

Payments

Pre-Debit Notifications

3DS2 Setup

Unreferenced Refunds

Dry-run

Transaction Reporting

Routing Recommendations

Payment Links

Recipients for Marketplace

Sellers (Franchise)

Subscriptions Plans

Subscriptions

Payouts

Organizations

Reports

Installments

AI Caller

Communications Campaigns

Conversion Rate

Banking Connectivity

Webhooks

Authorizations

Path Parameters

Response