Create Meter

POST

subscriptions

meters

Create Meter

curl --request POST \
  --url https://api-sandbox.y.uno/v1/subscriptions/meters \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "account_id": "00000000-0000-4000-8000-000000000002",
  "name": "AI tokens",
  "description": "LLM tokens consumed by model responses, reported once per response",
  "event_name": "ai_tokens",
  "aggregation": "SUM",
  "unit_label": "token",
  "plural_unit_label": "tokens",
  "default_price": {
    "currency": "USD",
    "value": 0.002
  },
  "metadata": [
    {
      "key": "team",
      "value": "platform"
    }
  ]
}
'

import requests

url = "https://api-sandbox.y.uno/v1/subscriptions/meters"

payload = {
    "account_id": "00000000-0000-4000-8000-000000000002",
    "name": "AI tokens",
    "description": "LLM tokens consumed by model responses, reported once per response",
    "event_name": "ai_tokens",
    "aggregation": "SUM",
    "unit_label": "token",
    "plural_unit_label": "tokens",
    "default_price": {
        "currency": "USD",
        "value": 0.002
    },
    "metadata": [
        {
            "key": "team",
            "value": "platform"
        }
    ]
}
headers = {
    "X-Idempotency-Key": "<x-idempotency-key>",
    "public-api-key": "<api-key>",
    "private-secret-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': '<x-idempotency-key>',
    'public-api-key': '<api-key>',
    'private-secret-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    account_id: '00000000-0000-4000-8000-000000000002',
    name: 'AI tokens',
    description: 'LLM tokens consumed by model responses, reported once per response',
    event_name: 'ai_tokens',
    aggregation: 'SUM',
    unit_label: 'token',
    plural_unit_label: 'tokens',
    default_price: {currency: 'USD', value: 0.002},
    metadata: [{key: 'team', value: 'platform'}]
  })
};

fetch('https://api-sandbox.y.uno/v1/subscriptions/meters', 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/meters",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'account_id' => '00000000-0000-4000-8000-000000000002',
    'name' => 'AI tokens',
    'description' => 'LLM tokens consumed by model responses, reported once per response',
    'event_name' => 'ai_tokens',
    'aggregation' => 'SUM',
    'unit_label' => 'token',
    'plural_unit_label' => 'tokens',
    'default_price' => [
        'currency' => 'USD',
        'value' => 0.002
    ],
    'metadata' => [
        [
                'key' => 'team',
                'value' => 'platform'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Idempotency-Key: <x-idempotency-key>",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.y.uno/v1/subscriptions/meters"

	payload := strings.NewReader("{\n  \"account_id\": \"00000000-0000-4000-8000-000000000002\",\n  \"name\": \"AI tokens\",\n  \"description\": \"LLM tokens consumed by model responses, reported once per response\",\n  \"event_name\": \"ai_tokens\",\n  \"aggregation\": \"SUM\",\n  \"unit_label\": \"token\",\n  \"plural_unit_label\": \"tokens\",\n  \"default_price\": {\n    \"currency\": \"USD\",\n    \"value\": 0.002\n  },\n  \"metadata\": [\n    {\n      \"key\": \"team\",\n      \"value\": \"platform\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
	req.Header.Add("public-api-key", "<api-key>")
	req.Header.Add("private-secret-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.y.uno/v1/subscriptions/meters")
  .header("X-Idempotency-Key", "<x-idempotency-key>")
  .header("public-api-key", "<api-key>")
  .header("private-secret-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"account_id\": \"00000000-0000-4000-8000-000000000002\",\n  \"name\": \"AI tokens\",\n  \"description\": \"LLM tokens consumed by model responses, reported once per response\",\n  \"event_name\": \"ai_tokens\",\n  \"aggregation\": \"SUM\",\n  \"unit_label\": \"token\",\n  \"plural_unit_label\": \"tokens\",\n  \"default_price\": {\n    \"currency\": \"USD\",\n    \"value\": 0.002\n  },\n  \"metadata\": [\n    {\n      \"key\": \"team\",\n      \"value\": \"platform\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["public-api-key"] = '<api-key>'
request["private-secret-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"account_id\": \"00000000-0000-4000-8000-000000000002\",\n  \"name\": \"AI tokens\",\n  \"description\": \"LLM tokens consumed by model responses, reported once per response\",\n  \"event_name\": \"ai_tokens\",\n  \"aggregation\": \"SUM\",\n  \"unit_label\": \"token\",\n  \"plural_unit_label\": \"tokens\",\n  \"default_price\": {\n    \"currency\": \"USD\",\n    \"value\": 0.002\n  },\n  \"metadata\": [\n    {\n      \"key\": \"team\",\n      \"value\": \"platform\"\n    }\n  ]\n}"

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

{
  "id": "55555555-5555-5555-5555-555555555555",
  "account_id": "00000000-0000-4000-8000-000000000002",
  "name": "AI tokens",
  "description": "LLM tokens consumed by model responses, reported once per response",
  "event_name": "ai_tokens",
  "aggregation": "SUM",
  "unit_label": "token",
  "plural_unit_label": "tokens",
  "default_price": {
    "currency": "USD",
    "value": 0.002
  },
  "metadata": [
    {
      "key": "team",
      "value": "platform"
    }
  ],
  "status": "ACTIVE",
  "created_at": "2026-08-18T09:00:04.000000Z",
  "updated_at": "2026-08-18T09:00:04.000000Z"
}

Enabled per organizationUsage-based billing must be enabled for your organization before these endpoints accept requests. Contact your Yuno account manager to enable it. Requests from an organization where it is not enabled return 403 PRODUCT_NOT_ENABLED.

event_name and aggregation are immutableThey define what your systems send and how it counts, so they can’t change after creation (a PATCH that includes them is silently ignored). To change either, create a new meter with a new event_name and archive the old one with Update Meter (status: INACTIVE). event_name is unique per account across active and archived meters, so pick a name you won’t need to reuse. status sent on creation is ignored — a new meter is always ACTIVE.

See The Meter Object for every field, and the Usage-Based Billing guide for the end-to-end flow. Refer to Meter Error Codes for the possible error outcomes.

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-Idempotency-Key

string

required

Unique identifier used in HTTP headers to ensure that a request is processed only once, even if it is retried due to network issues or timeouts. Optional, as on the rest of the Yuno API.

Body

application/json

account_id

string

required

The unique identifier of the account the meter belongs to (UUID, 36 chars).

name

string

required

The meter display name (MAX 255; MIN 3). Leading and trailing spaces are trimmed.

event_name

string

required

The key your systems send on every usage event to reference this meter (MAX 100; lowercase letters, digits, _ and . only — ^[a-z0-9_.]+$). Must be unique across all meters of the account, ACTIVE or INACTIVE, else 409 METER_EVENT_NAME_CONFLICT. Immutable after creation.

aggregation

enum<string>

required

How reported events roll up into the cycle quantity. SUM adds every event value (tokens, minutes). COUNT counts events, ignoring value (API requests). LAST keeps the most recent value (a gauge such as gigabytes held). Immutable after creation.

Available options:

SUM,

COUNT,

LAST

description

string

What the meter counts and how. Optional but recommended — it is how your team and Yuno support understand the meter.

unit_label

string

Singular unit label used when the usage is displayed. Example: token.

plural_unit_label

string

Plural unit label used when the usage is displayed. Example: tokens.

default_price

object

Show child attributes

metadata

object[]

Optional key-value pairs attached to the meter (MAX 48 entries; keys must be unique per meter).

Show child attributes

status

enum<string>

Ignored on creation — a new meter is always ACTIVE. Use Update Meter to archive it.

Available options:

ACTIVE,

INACTIVE

Response

201

string

The unique identifier of the meter.

account_id

string

The unique identifier of the account that owns the meter.

name

string

description

string | null

event_name

string

aggregation

enum<string>

Available options:

SUM,

COUNT,

LAST

unit_label

string | null

plural_unit_label

string | null

default_price

object

Show child attributes

metadata

object[]

Show child attributes

status

enum<string>

Available options:

ACTIVE,

INACTIVE

Example:

"ACTIVE"

created_at

string

Set by Yuno on creation.

updated_at

string

Set by Yuno on every update.

⌘I

Create Meter

curl --request POST \
  --url https://api-sandbox.y.uno/v1/subscriptions/meters \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "account_id": "00000000-0000-4000-8000-000000000002",
  "name": "AI tokens",
  "description": "LLM tokens consumed by model responses, reported once per response",
  "event_name": "ai_tokens",
  "aggregation": "SUM",
  "unit_label": "token",
  "plural_unit_label": "tokens",
  "default_price": {
    "currency": "USD",
    "value": 0.002
  },
  "metadata": [
    {
      "key": "team",
      "value": "platform"
    }
  ]
}
'

import requests

url = "https://api-sandbox.y.uno/v1/subscriptions/meters"

payload = {
    "account_id": "00000000-0000-4000-8000-000000000002",
    "name": "AI tokens",
    "description": "LLM tokens consumed by model responses, reported once per response",
    "event_name": "ai_tokens",
    "aggregation": "SUM",
    "unit_label": "token",
    "plural_unit_label": "tokens",
    "default_price": {
        "currency": "USD",
        "value": 0.002
    },
    "metadata": [
        {
            "key": "team",
            "value": "platform"
        }
    ]
}
headers = {
    "X-Idempotency-Key": "<x-idempotency-key>",
    "public-api-key": "<api-key>",
    "private-secret-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': '<x-idempotency-key>',
    'public-api-key': '<api-key>',
    'private-secret-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    account_id: '00000000-0000-4000-8000-000000000002',
    name: 'AI tokens',
    description: 'LLM tokens consumed by model responses, reported once per response',
    event_name: 'ai_tokens',
    aggregation: 'SUM',
    unit_label: 'token',
    plural_unit_label: 'tokens',
    default_price: {currency: 'USD', value: 0.002},
    metadata: [{key: 'team', value: 'platform'}]
  })
};

fetch('https://api-sandbox.y.uno/v1/subscriptions/meters', 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/meters",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'account_id' => '00000000-0000-4000-8000-000000000002',
    'name' => 'AI tokens',
    'description' => 'LLM tokens consumed by model responses, reported once per response',
    'event_name' => 'ai_tokens',
    'aggregation' => 'SUM',
    'unit_label' => 'token',
    'plural_unit_label' => 'tokens',
    'default_price' => [
        'currency' => 'USD',
        'value' => 0.002
    ],
    'metadata' => [
        [
                'key' => 'team',
                'value' => 'platform'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Idempotency-Key: <x-idempotency-key>",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.y.uno/v1/subscriptions/meters"

	payload := strings.NewReader("{\n  \"account_id\": \"00000000-0000-4000-8000-000000000002\",\n  \"name\": \"AI tokens\",\n  \"description\": \"LLM tokens consumed by model responses, reported once per response\",\n  \"event_name\": \"ai_tokens\",\n  \"aggregation\": \"SUM\",\n  \"unit_label\": \"token\",\n  \"plural_unit_label\": \"tokens\",\n  \"default_price\": {\n    \"currency\": \"USD\",\n    \"value\": 0.002\n  },\n  \"metadata\": [\n    {\n      \"key\": \"team\",\n      \"value\": \"platform\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
	req.Header.Add("public-api-key", "<api-key>")
	req.Header.Add("private-secret-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.y.uno/v1/subscriptions/meters")
  .header("X-Idempotency-Key", "<x-idempotency-key>")
  .header("public-api-key", "<api-key>")
  .header("private-secret-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"account_id\": \"00000000-0000-4000-8000-000000000002\",\n  \"name\": \"AI tokens\",\n  \"description\": \"LLM tokens consumed by model responses, reported once per response\",\n  \"event_name\": \"ai_tokens\",\n  \"aggregation\": \"SUM\",\n  \"unit_label\": \"token\",\n  \"plural_unit_label\": \"tokens\",\n  \"default_price\": {\n    \"currency\": \"USD\",\n    \"value\": 0.002\n  },\n  \"metadata\": [\n    {\n      \"key\": \"team\",\n      \"value\": \"platform\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["public-api-key"] = '<api-key>'
request["private-secret-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"account_id\": \"00000000-0000-4000-8000-000000000002\",\n  \"name\": \"AI tokens\",\n  \"description\": \"LLM tokens consumed by model responses, reported once per response\",\n  \"event_name\": \"ai_tokens\",\n  \"aggregation\": \"SUM\",\n  \"unit_label\": \"token\",\n  \"plural_unit_label\": \"tokens\",\n  \"default_price\": {\n    \"currency\": \"USD\",\n    \"value\": 0.002\n  },\n  \"metadata\": [\n    {\n      \"key\": \"team\",\n      \"value\": \"platform\"\n    }\n  ]\n}"

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

{
  "id": "55555555-5555-5555-5555-555555555555",
  "account_id": "00000000-0000-4000-8000-000000000002",
  "name": "AI tokens",
  "description": "LLM tokens consumed by model responses, reported once per response",
  "event_name": "ai_tokens",
  "aggregation": "SUM",
  "unit_label": "token",
  "plural_unit_label": "tokens",
  "default_price": {
    "currency": "USD",
    "value": 0.002
  },
  "metadata": [
    {
      "key": "team",
      "value": "platform"
    }
  ],
  "status": "ACTIVE",
  "created_at": "2026-08-18T09:00:04.000000Z",
  "updated_at": "2026-08-18T09:00:04.000000Z"
}

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

Headers

Body

Response