---
title: "The Metronome draft and the Stripe invoice list"
method: GET
path: "/api/v1/organizations/{organization_id}/billing/invoices"
tags: ["organizations"]
---

# The Metronome draft and the Stripe invoice list

`GET /api/v1/organizations/{organization_id}/billing/invoices`

## Request

- Base URL: `https://composal.com` (the document declares no server; this is the origin it was published from)
- URL: `https://composal.com/api/v1/organizations/{organization_id}/billing/invoices`
- Auth: HTTP bearer

`upcoming` is what Metronome would invoice now (the current draft total, its period, and the credit balance that offsets it), null without a subscription or when the preview is unavailable. `invoices` is the organization's Stripe invoices, newest first, with the hosted page and PDF links; empty without a Stripe customer. Cached for a minute per organization. Any member may read it. This is its own read rather than part of the page contract because Stripe answers slowly and the usage page must not wait on it.

## Path parameters

- `organization_id` string, required

## Response `200`

Invoices

- BillingInvoicesPage
  - `organization_id` string, required
  - `upcoming` BillingUpcomingInvoice, required
    - `total_cents` integer, required: The Metronome draft total
    - `currency` string, required
    - `period_started_at` string, nullable
    - `period_ended_at` string, nullable
    - `credit_balance_cents` integer, required: Remaining credit that offsets the draft.
    - `metronome_invoice_ids` string[], required
  - `invoices` BillingInvoice[], required
    - `id` string, required
    - `number` string, nullable
    - `status` 'draft' | 'open' | 'paid' | 'uncollectible' | 'void', required
    - `currency` string, required
    - `total_cents` integer, required
    - `amount_due_cents` integer, required
    - `period_started_at` string, nullable
    - `period_ended_at` string, nullable
    - `created_at` string, required
    - `hosted_invoice_url` string, nullable
    - `invoice_pdf` string, nullable
    - `metronome_invoice_id` string, nullable: Metronome's id for the invoice it pushed

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `422`: Unprocessable entity
- `502`: Bad gateway

---

[API](https://skmtc.dev/composal/apis/vex-api.md) - [All operations](https://skmtc.dev/composal/apis/vex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/composal/apis/vex-api/revisions/19698ba051dc?raw)