# Billing API

Version 1.0 · OpenAPI 3.1.0

Read what your organization uses and owes from scripts and finance tools:
the month's usage and projection, itemised usage, monthly statements,
payments, the credit balance, the rate card, and the term commitment.
Keep the billing details invoices are made out to up to date, and manage
saved cards.

EvoHub is billed by usage, measured in **EHU** (EvoHub Units). Each
metric has an EHU weight on the rate card, and each pricing tier a price
per EHU, so every charge can be reproduced by hand. Each month's free
allowance is applied before anything is charged.

**Authentication.** Every endpoint except the published price list
(`/api/v1/pricing`) and the current campaign (`/api/v1/campaigns/active`)
takes an EvoHub API key, sent as `Authorization: Bearer evohub_…` or as
`X-API-Key: evohub_…`. Each operation names the scope the key needs in its
description and in `x-evohub-permission`. A missing or invalid key gets
**401**; a valid key without the scope gets **403** `FORBIDDEN`, never
401. See the [API overview](/api-overview),
[API keys and scopes](/api-keys-and-scopes) and [Errors](/errors).

**What a key cannot do.** Adding a card and buying credit both end with
the card being confirmed in the browser, inside the console's secure card
form; they are listed in `x-route-check.not-public` and are done in the
console.

**Responses.** A successful answer carries its result in `data`. Errors
carry an `error` object with a machine-readable `code`, a `message` and a
`request_id` (also sent in the `X-Request-ID` header — quote it to
support). Amounts are in US dollars (`_usd`) or EHU (`_ehu`). Timestamps
are RFC 3339 in UTC; dates are `YYYY-MM-DD` and billing periods are UTC
calendar months.

**Payments not enabled.** Endpoints that read or change cards and
billing details answer **503** `PAYMENTS_DISABLED` when payments are not
enabled for the environment.

## Servers

- `https://evohub.io`

## Authentication

- `bearerKey`: HTTP Bearer — An EvoHub API key (`evohub_…`) as a bearer token.
- `headerKey`: API key in the header `X-API-Key` — An EvoHub API key (`evohub_…`).

## Usage

This month's usage, projection and allowance, and itemised usage over any range.

- [GET /api/v1/billing/summary](https://docs.evohub.io/billing/get-billing-summary.md): Get this month's summary
- [GET /api/v1/billing/usage](https://docs.evohub.io/billing/get-usage.md): Get itemised usage

## Statements

Monthly bills and everything charged to the organization.

- [GET /api/v1/billing/statements](https://docs.evohub.io/billing/list-statements.md): List statements
- [GET /api/v1/billing/statements/{period}](https://docs.evohub.io/billing/get-statement.md): Get one statement
- [GET /api/v1/billing/payments](https://docs.evohub.io/billing/list-payments.md): List payments

## Rate card

The EHU weight of every metric and the price per EHU.

- [GET /api/v1/billing/rate-card](https://docs.evohub.io/billing/get-rate-card.md): Get the rate card in force
- [GET /api/v1/pricing](https://docs.evohub.io/billing/get-pricing.md): Get published pricing

## Credit

The prepaid EHU balance and its history.

- [GET /api/v1/billing/credit](https://docs.evohub.io/billing/get-credit.md): Get the credit balance

## Payment methods

Cards saved for the organization.

- [GET /api/v1/billing/payment-methods](https://docs.evohub.io/billing/list-payment-methods.md): List saved cards
- [POST /api/v1/billing/payment-methods/{id}/default](https://docs.evohub.io/billing/set-default-payment-method.md): Make a card the default
- [DELETE /api/v1/billing/payment-methods/{id}](https://docs.evohub.io/billing/remove-payment-method.md): Remove a card

## Billing details

Who invoices are made out to, and the tax registration.

- [GET /api/v1/billing/profile](https://docs.evohub.io/billing/get-billing-profile.md): Get billing details
- [PUT /api/v1/billing/profile](https://docs.evohub.io/billing/set-billing-profile.md): Set billing details
- [GET /api/v1/billing/tax-details](https://docs.evohub.io/billing/get-tax-details.md): Get tax details
- [PUT /api/v1/billing/tax-details](https://docs.evohub.io/billing/set-tax-id.md): Set the tax number

## Commitment

A monthly volume agreed for a fixed term, at a lower price per EHU.

- [GET /api/v1/billing/commitment](https://docs.evohub.io/billing/get-commitment.md): Get the commitment
- [POST /api/v1/billing/commitment](https://docs.evohub.io/billing/accept-commitment.md): Enter a commitment
- [DELETE /api/v1/billing/commitment](https://docs.evohub.io/billing/end-commitment.md): End the commitment early

## Campaigns

Credit campaigns and where the organization stands with them.

- [GET /api/v1/billing/campaign](https://docs.evohub.io/billing/get-campaign-status.md): Get the organization's campaign standing
- [GET /api/v1/campaigns/active](https://docs.evohub.io/billing/get-active-campaign.md): Get the running campaign