COSS
Billing

Retrieve an invoice

GET
/v1/billing/invoices/{id}

One invoice with its lines.

Authorization

bearerAuth
headerAuthorizationBearer <token>

A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.

Path Parameters

id*string

The invoice's id.

Header Parameters

Coss-Version?"2026-10-10"

The API version (a date) to use for this request. Defaults to your organization's version, pinned to the latest one when it first used the API and upgraded from the dashboard. The SDK always sends the version it was built for.

Value in"2026-10-10"

Response Body

The invoice.

application/json
  1. response
object*"invoice"
Value in"invoice"
id*string
number*string|null
kind*string
Value in"period""plan_change""one_off""final"
status*string
Value in"open""paid""void""uncollectible"
currency*"usd"
Value in"usd"
period*
subtotal*integer

An amount in cents (USD).

discount*integer

An amount in cents (USD).

credit*integer

An amount in cents (USD).

tax*integer

An amount in cents (USD).

total*integer

An amount in cents (USD).

amount_paid*integer

An amount in cents (USD).

amount_due*integer

An amount in cents (USD).

collection_method*string
Value in"charge_automatically""send_invoice"
due_at*|
Formatdate-time
finalized_at*|
Formatdate-time
paid_at*|
Formatdate-time
voided_at*|
Formatdate-time
hosted_url*|

A page to view (and pay) the invoice.

pdf_url*string|null
lines*array<>
import { Coss } from "coss";const coss = new Coss({  apiKey: process.env.COSS_API_KEY,  baseUrl: "https://api.coss.com",});const { data, error } = await coss.billing.invoices.get("inv_01k7c8m4q2f3e9v6t5r1n0p8yz");
{  "object": "invoice",  "id": "inv_01k7c8m4q2f3e9v6t5r1n0p8yz",  "number": "COSS-000042",  "kind": "period",  "status": "paid",  "currency": "usd",  "period": {    "start": "2026-10-01T00:00:00.000Z",    "end": "2026-11-01T00:00:00.000Z"  },  "subtotal": 7300,  "discount": 0,  "credit": 2500,  "tax": 0,  "total": 4800,  "amount_paid": 4800,  "amount_due": 0,  "collection_method": "charge_automatically",  "due_at": "2026-11-01T00:20:00.000Z",  "finalized_at": "2026-11-01T00:20:00.000Z",  "paid_at": "2026-11-01T00:21:00.000Z",  "voided_at": null,  "hosted_url": "https://invoice.stripe.com/i/acct_123/test_YWNjdF8x",  "pdf_url": "https://pay.stripe.com/invoice/acct_123/test_YWNjdF8x/pdf",  "lines": [    {      "object": "invoice_line",      "id": "invl_01k7c8m4q2f3e9v6t5r1n0p8yz",      "kind": "usage",      "description": "Email: 120,000 recipients",      "meter": "email.recipients",      "dimension": null,      "quantity": 120000,      "included_quantity": 0,      "unit_price": "0.0004",      "amount": 4800,      "period": {        "start": "2026-10-01T00:00:00.000Z",        "end": "2026-11-01T00:00:00.000Z"      }    }  ]}

Retrieve the organization's billing GET

The organization's plan (and contract), the current billing month's usage and what it would add to the next invoice so far, its standing (`past_due`, billing holds), payment method, and what the plan includes. Organization-wide: every environment's key sees the same. Plan changes are made in the dashboard; subscribe to the `billing.*` webhook events to follow them.

List usage GET

Billable usage over a range (the current billing month by default), per meter, dimension and bucket (`hour`, `day` or `month`, UTC), oldest first; with `group_by=environment`, per environment too. Only live environments are billed, so only they appear. Usage counts when it becomes billable (an email when the provider accepts it) and is kept for 400 days.