Public cost-dashboard projection (ADR-032)
const url = 'http://localhost:8080/v1/public/cost-dashboard/example';const options = {method: 'GET'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url http://localhost:8080/v1/public/cost-dashboard/exampleUnauthenticated. The hc_pcd_… token in the URL is the sole
credential — partners embed via iframe / fetch from their own
app without an API key. Sanitized projection: customer_id,
tenant_id, livemode, billing_period, subscriptions, usage[],
totals, projected_total_cents, credits. PII (email, display_name, external_id,
metadata, billing_profile) is NEVER on this response. Wrong
prefix or unknown token → 401 (anti-enumeration). No active
sub → 200 with billing_period.source = "no_subscription":
subscriptions, usage and totals are empty, and credits
still lists the customer’s credit balance.
Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Responses
Section titled “Responses”Projection
object
object
Branch on this before rendering the period. When it is no_subscription the customer has no active subscription, subscriptions, usage and totals are empty (credits is not), and start/end carry the zero time (0001-01-01T00:00:00Z) rather than a real range — display them and the page reads “January 1, year 1”.
object
object
One row per price that took usage this period.
object
The labels the price takes. Absent for a price that takes every event.
object
Per-unit price in DECIMAL CENTS (ADR-045, the Stripe unit_amount_decimal model) — NOT dollars. “0.0003” is 0.0003 CENTS per unit ($3.00 per 1M units); multiplying it by quantity yields CENTS, matching the sibling amount_cents. Reading it as dollars overstates the cost 100x.
One entry per currency present in usage.
object
The metered cost of the current billing period so far, in cents, including usage a threshold invoice already billed. Recurring base fees are not included — an in_advance base is already invoiced at period open.
The customer’s credit position, one entry per currency, ordered by currency. balance_cents is the ledger balance in that currency, less any grant past its expiry date that is not yet written off: credit is drawn down when an invoice is issued, so it does not move with usage. unbilled_usage_cents is the usage no invoice has billed yet that will be invoiced in that currency, and estimated_remaining_cents is the balance minus that, never below zero. These three are the same figures GET /v1/credits/balance/{customer_id}/live returns. unbilled_usage_cents differs from projected_total_cents after a threshold invoice: it leaves out the usage that invoice billed. It is an estimate: tax, base fees billed at period end and unpaid invoices are not subtracted.
object
What is left of the customer’s prepaid commit.
What is left of promotional credit.
Example
{ "billing_period": { "source": "subscription" }}Invalid token
Rate limited (60/min/IP)