Retrieve Subscription Usage

GET

subscriptions

{subscription_id}

usage

curl --request GET \
  --url https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/usage \
  --header 'X-Account-Code: <x-account-code>' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>'

import requests

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

headers = {
    "X-Account-Code": "<x-account-code>",
    "public-api-key": "<api-key>",
    "private-secret-key": "<api-key>"
}

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

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Account-Code': '<x-account-code>',
    'public-api-key': '<api-key>',
    'private-secret-key': '<api-key>'
  }
};

fetch('https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/usage', 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}/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Account-Code: <x-account-code>",
    "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}/usage"

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

	req.Header.Add("X-Account-Code", "<x-account-code>")
	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}/usage")
  .header("X-Account-Code", "<x-account-code>")
  .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}/usage")

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

request = Net::HTTP::Get.new(url)
request["X-Account-Code"] = '<x-account-code>'
request["public-api-key"] = '<api-key>'
request["private-secret-key"] = '<api-key>'

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

{
  "subscription_code": "c2094820-df10-4bd4-b7ef-dbe0d28db857",
  "period": {
    "start": "2026-09-15T15:54:32.436443Z",
    "end": "2026-10-15T15:54:32.272111Z"
  },
  "currency": "COP",
  "items": [
    {
      "meter_code": "b7cb6aad-0fcc-4898-ae8b-f500ee6dfbb3",
      "event_name": "lifecycle_1789487669444",
      "aggregation": "SUM",
      "quantity": 20,
      "credits": 0,
      "billable_quantity": 20,
      "remaining_credits": 0,
      "unit_price": {
        "currency": "COP",
        "value": 500
      },
      "amount": {
        "currency": "COP",
        "value": 10000
      },
      "events_count": 2,
      "last_event_at": "2026-09-15T15:54:46.620383Z"
    }
  ],
  "total": {
    "currency": "COP",
    "value": 10000
  }
}

{
  "code": "INVALID_CREDENTIALS",
  "messages": [
    "Invalid Credentials"
  ]
}

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

Returns the metered usage a subscription has accrued in its current billing period, priced by the meters attached to its plan — one item per meter, with the aggregated quantity, the quantity that is actually billable after any included credits are consumed, the unit price and the resulting amount, plus a total for the period. This is a read: it does not itself trigger billing. See Usage-Based Billing for how a subscription accrues meters, credits and pricing in the first place.

Reading the response

Field	Meaning
`subscription_code`	The subscription the usage belongs to — the `id` you passed in the path.
`currency`	The subscription’s currency — what every `unit_price`, `amount` and `total` on this page is denominated in.
`period.start` / `period.end`	The subscription’s current billing period — the window `items` is aggregated over.
`items[].meter_code`	The meter this item aggregates.
`items[].event_name`	The meter’s `event_name` — what your usage events report against.
`items[].aggregation`	`SUM`, `COUNT` or `LAST` — see Choosing an aggregation.
`items[].quantity`	The aggregated quantity reported for this meter in the period.
`items[].credits`	How much of the meter’s included credits this item’s quantity consumed.
`items[].billable_quantity`	The quantity actually billable after `credits` are consumed.
`items[].remaining_credits`	Included credits left unused for this meter in the period.
`items[].unit_price`	The price of one billable unit.
`items[].amount`	`billable_quantity` priced at `unit_price`.
`items[].events_count`	How many usage events were reported against this meter in the period.
`items[].last_event_at`	When the most recent of those events was reported.
`total`	The sum of every item’s `amount` for the period. Zero when `items` is empty.

Every quantity and amount is a JSON number.

A subscription with one metered item

{
  "subscription_code": "c2094820-df10-4bd4-b7ef-dbe0d28db857",
  "period": {
    "start": "2026-09-15T15:54:32.436443Z",
    "end": "2026-10-15T15:54:32.272111Z"
  },
  "currency": "COP",
  "items": [
    {
      "meter_code": "b7cb6aad-0fcc-4898-ae8b-f500ee6dfbb3",
      "event_name": "lifecycle_1789487669444",
      "aggregation": "SUM",
      "quantity": 20,
      "credits": 0,
      "billable_quantity": 20,
      "remaining_credits": 0,
      "unit_price": { "currency": "COP", "value": 500 },
      "amount": { "currency": "COP", "value": 10000 },
      "events_count": 2,
      "last_event_at": "2026-09-15T15:54:46.620383Z"
    }
  ],
  "total": { "currency": "COP", "value": 10000 }
}

When there is nothing to bill

A subscription whose plan has no meters, or that has no plan at all, returns items: [] and a zero total rather than an error.

Reporting is asynchronousPOST /subscriptions/meters/events answers 202 once the event is validated, before it is stored. A usage read that lands moments after reporting an event can still show the total from before that event — a subscription’s items stayed at the same quantity and events_count on a read taken immediately after a further event was reported on stg. Allow a short delay before relying on a read to reflect the very latest report.

Errors

HTTP	`code`	When
`401`	`INVALID_CREDENTIALS`	The `public-api-key` / `private-secret-key` pair is missing or invalid.
`404`	`NOT_FOUND`	The subscription does not exist — `"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

Headers

X-Account-Code

string

required

The account_id found in your Yuno Dashboard (UUID).

Path Parameters

subscription_id

string

required

The unique identifier of the subscription.

Response

200

subscription_code

string

Example:

"c2094820-df10-4bd4-b7ef-dbe0d28db857"

period

object

The subscription's current billing period.

Show child attributes

currency

string

Example:

"COP"

items

object[]

One entry per meter attached to the subscription's plan. Empty when the plan has no meters, or the subscription has no plan.

Show child attributes

total

object

The sum of every item's amount for the period. Zero when items is empty.

Show child attributes

⌘I

Retrieve Subscription Usage

curl --request GET \
  --url https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/usage \
  --header 'X-Account-Code: <x-account-code>' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>'

import requests

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

headers = {
    "X-Account-Code": "<x-account-code>",
    "public-api-key": "<api-key>",
    "private-secret-key": "<api-key>"
}

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

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Account-Code': '<x-account-code>',
    'public-api-key': '<api-key>',
    'private-secret-key': '<api-key>'
  }
};

fetch('https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/usage', 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}/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Account-Code: <x-account-code>",
    "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}/usage"

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

	req.Header.Add("X-Account-Code", "<x-account-code>")
	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}/usage")
  .header("X-Account-Code", "<x-account-code>")
  .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}/usage")

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

request = Net::HTTP::Get.new(url)
request["X-Account-Code"] = '<x-account-code>'
request["public-api-key"] = '<api-key>'
request["private-secret-key"] = '<api-key>'

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

{
  "subscription_code": "c2094820-df10-4bd4-b7ef-dbe0d28db857",
  "period": {
    "start": "2026-09-15T15:54:32.436443Z",
    "end": "2026-10-15T15:54:32.272111Z"
  },
  "currency": "COP",
  "items": [
    {
      "meter_code": "b7cb6aad-0fcc-4898-ae8b-f500ee6dfbb3",
      "event_name": "lifecycle_1789487669444",
      "aggregation": "SUM",
      "quantity": 20,
      "credits": 0,
      "billable_quantity": 20,
      "remaining_credits": 0,
      "unit_price": {
        "currency": "COP",
        "value": 500
      },
      "amount": {
        "currency": "COP",
        "value": 10000
      },
      "events_count": 2,
      "last_event_at": "2026-09-15T15:54:46.620383Z"
    }
  ],
  "total": {
    "currency": "COP",
    "value": 10000
  }
}

{
  "code": "INVALID_CREDENTIALS",
  "messages": [
    "Invalid Credentials"
  ]
}

{
  "code": "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

FX Rates

Banking Connectivity

Webhooks

Reading the response

When there is nothing to bill

Errors

Authorizations

Headers

Path Parameters

Response

​Reading the response

​When there is nothing to bill

​Errors

Authorizations

Headers

Path Parameters

Response

Reading the response

When there is nothing to bill

Errors