---
title: "Get billing"
method: GET
path: "/billing"
tags: ["Organization settings"]
---

# Get billing

`GET /billing`

## Request

- Base URL: `https://api.primitive.dev/v1`
- URL: `https://api.primitive.dev/v1/billing`
- Auth: HTTP bearer

The plan, how it is paid for, the subscription state, the ten most recent invoices, and the usage statements of the twelve most recent statemented billing periods (closing, closed or uncollectible), and a preview of the open billing period's usage so far, priced as its statement will be (amounts in micros or cents as decimal strings; zero lines for features the organization cannot use, and for retired usage kinds, are left out). A part that could not be read just now is empty and its error field (invoices_error, usage_statements_error, usage_error) says so; the rest still answers. Changing the plan or the payment method stays in the dashboard.

Person only: a dashboard session. The person's role must hold billing:read. API keys, agent connection keys and agents are refused.

## Response `200`

Success

- object
  - `success` true, required
  - `data` OrgSettingsGetBillingResult, required
    - `plan` string, required
    - `source` 'stripe' | 'comp' | 'developer' | 'unknown', required
    - `subscription_status` string, nullable, required
    - `current_period_end` string, date-time, nullable, required
    - `cancel_at_period_end` boolean, required
    - `upgraded_by_email` string, nullable, required
    - `upgraded_by_name` string, nullable, required
    - `comp_reason` string, nullable, required
    - `invoices` object[], required
      - `id` string, required
      - `number` string, nullable, required
      - `status` string, nullable, required
      - `amount_paid` number, required
      - `currency` string, required
      - `created_at` string, date-time, required
      - `hosted_invoice_url` string, nullable, required
      - `invoice_pdf` string, nullable, required
    - `invoices_error` string, nullable, required
    - `usage_statements` object[], required
      - `billing_period_id` string, required
      - `plan_key` string, required
      - `status` 'closing' | 'closed' | 'uncollectible', required
      - `period_start` string, date-time, required
      - `period_end` string, date-time, required
      - `currency` string, required
      - `credit_grant_micros` string, required
      - `statement_generated_at` string, date-time, required
      - `finalized_at` string, date-time, nullable, required
      - `stripe_invoice_id` string, nullable, required
      - `stripe_invoice_status` 'draft' | 'open' | 'paid' | 'void' | 'uncollectible', nullable, required
      - `stripe_invoice_lifecycle_status` 'not_invoiced' | 'unknown' | 'invoiced' | 'paid' | 'payment_failed' | 'void' | 'uncollectible', required
      - `stripe_invoice_lifecycle_updated_at` string, date-time, nullable, required
      - `stripe_invoice_paid_at` string, date-time, nullable, required
      - `stripe_invoice_payment_failed_at` string, date-time, nullable, required
      - `stripe_invoice_voided_at` string, date-time, nullable, required
      - `stripe_invoice_marked_uncollectible_at` string, date-time, nullable, required
      - `lines` object[], required
        - `bucket_key` string, required
        - `display_name` string, required
        - `unit` string, required
        - `quantity` string, required
        - `currency` string, required
        - `unit_price_micros` string, required
        - `pricing_unit_quantity` string, required
        - `gross_micros` string, required
        - `credit_applied_micros` string, required
        - `prepaid_credit_applied_micros` string, required
        - `net_micros` string, required
        - `billable` boolean, required
      - `totals` object, required
        - `gross_micros` string, required
        - `credit_applied_micros` string, required
        - `prepaid_credit_applied_micros` string, required
        - `net_micros` string, required
        - `invoice_amount_cents` string, required
        - `forgiven_micros` string, required
        - `invoice_waived_reason` string, nullable, required
        - `invoice_waived_cents` string, nullable, required
    - `usage_statements_error` string, nullable, required
    - `usage_preview` object, nullable, required
      - `billing_period_id` string, required
      - `plan_key` string, required
      - `status` 'open', required
      - `period_start` string, date-time, required
      - `period_end` string, date-time, required
      - `currency` string, required
      - `credit_grant_micros` string, required
      - `last_rolled_up_at` string, date-time, nullable, required
      - `prepaid_credit_unavailable` boolean, required
      - `invoice_exemption` 'comp' | 'internal', nullable, required
      - `lines` object[], required
        - `bucket_key` string, required
        - `display_name` string, required
        - `unit` string, required
        - `quantity` string, required
        - `currency` string, required
        - `unit_price_micros` string, required
        - `pricing_unit_quantity` string, required
        - `gross_micros` string, required
        - `credit_applied_micros` string, required
        - `prepaid_credit_applied_micros` string, required
        - `net_micros` string, required
        - `billable` boolean, required
      - `totals` object, required
        - `gross_micros` string, required
        - `credit_applied_micros` string, required
        - `prepaid_credit_applied_micros` string, required
        - `net_micros` string, required
        - `invoice_amount_cents` string, required
        - `forgiven_micros` string, required
    - `usage_error` string, nullable, required

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key
- `403`: Authenticated caller lacks permission for the operation
- `404`: Resource not found
- `429`: Rate limit exceeded. The `ratelimit-*` headers describe the limiter that rejected this request, with its own limit and window, not the API budget that successful responses report. A limiter that reports only a wait sends `Retry-After` alone.

---

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