Money and currency

Every amount in the API is an integer in the currency’s minor unit, next to an ISO 4217 currency code. Integers keep sums and comparisons exact; there are no floating-point prices anywhere in the API.

Amount	Currency	Means
13510	USD	$135.10 (cents)
4420	GBP	£44.20 (pence)
15000	JPY	¥15,000 (the yen has no minor unit)

Divide by 10 to the power of the currency’s exponent, which is 2 for most currencies and 0 for a few (JPY, KRW, …). Don’t hard-code 100: use your platform’s currency data, as below.

TypeScript

samples/typescript/money.ts

// Money is an integer amount in the currency's minor unit (ISO 4217): cents for
// USD, pence for GBP, yen for JPY. Convert with the currency's own exponent and
// never add amounts of different currencies.
import { Status302 } from "@status302/sdk";

function formatMoney(minor: number, currency: string, locale = "en-US"): string {
  const format = new Intl.NumberFormat(locale, { style: "currency", currency });
  const exponent = format.resolvedOptions().maximumFractionDigits ?? 2;
  return format.format(minor / 10 ** exponent);
}

const status302 = new Status302({ apiKey: process.env.STATUS302_API_KEY, baseUrl: process.env.STATUS302_API_URL });
const { items } = await status302.get("/v1/events", { query: { limit: 1 } });
const event = items[0];
if (!event) throw new Error("the catalog has no upcoming events");

const metrics = await status302.get("/v1/events/{id}/metrics", { path: { id: event.id } });
for (const m of metrics.items) {
  if (m.currency === null || m.floor === null) continue;
  const median = m.median === null ? "n/a" : formatMoney(m.median, m.currency);
  console.log(`${event.name} [${m.scope}] floor ${formatMoney(m.floor, m.currency)}, median ${median} (all-in per ticket)`);
}

console.log(formatMoney(13510, "USD"), formatMoney(4420, "GBP"), formatMoney(15000, "JPY"));

Python

samples/python/money.py

# Money is an integer amount in the currency's minor unit (ISO 4217): cents for
# USD, pence for GBP, yen for JPY. Convert with the currency's own exponent and
# never add amounts of different currencies.
import os
from decimal import Decimal

from status302 import Status302

# ISO 4217 currencies whose minor unit is not 1/100 of the major unit.
EXPONENTS = {
    **dict.fromkeys(["BIF", "CLP", "DJF", "GNF", "ISK", "JPY", "KMF", "KRW", "PYG", "RWF", "UGX", "VND", "VUV", "XAF", "XOF", "XPF"], 0),
    **dict.fromkeys(["BHD", "IQD", "JOD", "KWD", "LYD", "OMR", "TND"], 3),
}


def to_major(minor: int, currency: str) -> Decimal:
    return Decimal(minor).scaleb(-EXPONENTS.get(currency.upper(), 2))


with Status302(os.environ["STATUS302_API_KEY"], base_url=os.environ.get("STATUS302_API_URL", "https://api.status302.com")) as status302:
    items = status302.list_events(limit=1)["items"]
    if not items:
        raise SystemExit("the catalog has no upcoming events")
    event = items[0]
    for m in status302.get_event_metrics(event["id"])["items"]:
        if m["currency"] is None or m["floor"] is None:
            continue
        print(f"{event['name']} [{m['scope']}] floor {to_major(m['floor'], m['currency'])} {m['currency']} (all-in per ticket)")

print(to_major(13510, "USD"), to_major(4420, "GBP"), to_major(15000, "JPY"))

Where amounts appear

Amounts are flat fields with a Minor suffix, or metric values, always with a currency field on the same object:

Object	Fields	Notes
Event metrics (GET /v1/events/{id}/metrics, metrics on catalog rows)	floor, median, avg24h, avg72h, avg7d, avg30d, saleAvg24h, saleAvg72h, volume24h	Per ticket, all-in, in currency. volume24h is the sum of sale prices.
Sales (GET /v1/events/{id}/sales, the feed, the sales topic)	priceMinor, listMinor	priceMinor is the all-in price per ticket, listMinor the list (face) price.
Inventory changes and map price levels	listMinor, totalMinor	List price and all-in total per seat.
Price ranges (priceRange on events)	minMinor, maxMinor	The face-value range Ticketmaster advertises for the event.
Totals (GET /v1/sales/summary)	{ "minor": …, "currency": … }	One total per currency.

All-in prices include the primary seller’s fees, as a buyer pays them; list prices are the face value before fees. Metrics are all-in throughout, so floors are comparable across markets.

Currencies

An event’s prices are in the currency it is sold in: US events in USD, UK events in GBP, Canadian events in CAD, and so on. The API does not convert currencies.

• Never add or compare amounts of different currencies. Group by currency first. GET /v1/sales/summary returns its volume as one total per currency for this reason.
• A metric’s currency can be null when its market has no priced inventory yet; the price fields are then null too.
• Currency codes are upper-case ISO 4217.

Percentages and counts

Changes such as chg24h and chg72h are fractions, not amounts: -0.125 means the floor fell 12.5 % over 24 hours. Sell-through is a fraction between 0 and 1. Inventory, sales and quantities are plain integer counts of tickets.