Getting started

Pricing and the CSMS usage fee

Ivora charges a usage fee per kWh of charging on your chargers. The default rate is 1 US cent per kWh; Ivora can agree a different rate for your team, or for one of its projects. The fee is invoiced monthly to your team's payment method on file: one invoice per team, with a line per project. This fee is Ivora's own and separate from what drivers pay you: driver payments go to your payment account or your own processor, never to Ivora.

Billing is per team (your company). A project is a tenant in the API. A team owns one or more projects, and the team owns the payment method, the rate, any waiver, the grace period and the invoices. Ivora links your projects into one team.

Access to the CSMS starts with a meeting with Ivora, after which Ivora grants your account access. Before you set up chargers, add a payment method.

Read a project's billing profile

GET /v1/tenants/{tenant_id}/billing-profile (scope billing:read, or the billing team role) returns:

Field	Meaning
`rate_cents_per_kwh`	The project's fee in US cents per kWh, a decimal string such as `"1.00"`
`rate_source`	`team` (the team's rate) or `project` (a rate Ivora set for this project)
`team`	The team's `id`, `name`, default `rate_cents_per_kwh`, `discount_percent` and its projects (`tenant_ids`)
`invoicing`	`monthly`
`status`	`active` (the team has a usable card), `grace`, `discounted` (a 100% discount: no card needed), `enterprise` (invoiced with net terms: no card needed), `past_due` (an invoice payment failed), `payment_method_required`, `suspended` (by Ivora), `waived` or `exempt`
`discount_percent`	The team's invoice discount set by Ivora, 0 to 100 (default 0). The invoice still shows usage at the normal rate, then the discount; at 100 the team needs no card and is invoiced $0
`waived`	Ivora waived the team's payment method requirement; a waived team gets no invoice
`csms_setup_allowed`	Whether new CSMS setup and control are allowed (see below)
`grace_ends_at`	End of the team's grace period, for teams that existed before the fee
`past_due_since`	When a payment of the team's monthly invoice first failed; cleared once it is paid
`payment_method`	The team card's `brand`, `last4`, `exp_month`, `exp_year` and `expired`; never the card number
`setup_pending`	A card setup was started and not yet synchronized
`payment_mode`	`test` outside production: preproduction and previews never use live Stripe
`current_month`	The project's usage so far this month and its estimated fee (below); `null` when the CSMS cannot be read

This month's usage

current_month is the project's share of this month's invoice so far, counted by the monthly invoice's rule (see Monthly invoices): the project's completed charging sessions that ended in the current UTC calendar month, each with its whole energy. A session still running counts once it ends.

Field	Meaning
`period`, `period_start`, `period_end`	The UTC month, such as `2026-10`, `2026-10-01T00:00:00+00:00` to `2026-11-01T00:00:00+00:00`
`energy_kwh`	kWh of the month's sessions as a decimal string, as the CSMS records it (`"6.941"`; `"0"` without sessions); never Wh
`transactions`	Number of those sessions
`billable_from`	When the team's usage starts to be billed: the later of the fee's release and `grace_ends_at`
`billable_kwh`, `billable_transactions`	The sessions that ended at or after `billable_from`: what the invoice bills
`held_transactions`	Billable sessions with an implausible reading, left out of the estimate; they hold the team's invoice until Ivora corrects them
`invoiced`, `not_invoiced_reason`	`false` with `internal`, `bench`, `waived` or `grace` (the grace period runs until `billable_from`) when this usage is not invoiced; `estimated_minor` is then `0`
`rate_cents_per_kwh`	The project's effective rate
`usage_minor`	The project's invoice line so far: `billable_kwh` × `rate_cents_per_kwh`, rounded half up to a whole cent
`discount_percent`, `discount_minor`	The team's discount and its amount on this line, rounded half up (the invoice rounds it once over all projects, so it can differ by a cent)
`estimated_minor`	`usage_minor` − `discount_minor`, in US cents
`as_of`	When the usage was read; it is cached for up to 60 seconds

It is an estimate: the invoice is final. The team's whole month, with every project and any carried balance, is GET .../billing-profile/usage (below). Staff see the same object for each project in a team's view.

/v1/capabilities reports the default rate, the unit, the monthly invoicing, the team billing account and the grace period under platform_fee.

Monthly invoices

After each month ends (UTC), Ivora invoices each team once, with a line per project: Ivora CSMS, <month>: <kWh> kWh x <rate> cents/kWh. The energy is that of the project's charging sessions that ended in the month, however they were paid: bills Ivora settles, external sessions your own processor settles, and free charging. A session that starts in one month and ends in the next counts in the month it ends. Each line is kWh x rate, rounded half up to a whole cent. A session that reaches Ivora after its month was invoiced (a charger that was offline) appears on the next invoice as a late sessions line; no session is ever billed twice. Sessions before the usage fee existed, and sessions that ended during the team's grace period, are never billed: billing starts at the later of the fee's release and grace_ends_at, so the first invoice may cover part of a month.

If Ivora gave the team a discount, the invoice shows the lines at the normal rate and then an Ivora discount N% line (the lines' total times N%, rounded half up to a whole cent).

The invoice is charged automatically to the team's card. A total below Stripe's 50-cent minimum is not invoiced: it is carried to the next month and appears there as its own line. Until the team has a card, the month's amount is carried too. A total of $0 after a 100% discount is still invoiced, as a record, and needs no card. Waived and Ivora internal teams are not invoiced; a balance carried earlier waits for the next invoiced month.

GET /v1/tenants/{tenant_id}/billing-profile/invoices (scope billing:read, or the billing team role) lists the team's invoices, newest first, with each month's status (open, paid, payment_failed, carried, ...), lines, amount_minor (US cents) and hosted_invoice_url, Stripe's page to view, download or pay the invoice.
GET /v1/tenants/{tenant_id}/billing-profile/usage (scope billing:read, or the billing team role) estimates the current month so far: kWh and amount per project, and any carried balance. billable_from is when the team's usage starts to be billed.

If a payment fails, the team becomes past_due and Ivora is alerted. A self-serve team keeps working for 14 days (an enterprise team keeps working: see Enterprise invoicing); after that, the requests below answer 402 payment_method_required until the invoice is paid at its hosted_invoice_url (or Stripe's automatic retry succeeds with an updated card). Charging, stops and reads are never affected.

Enterprise invoicing

For large accounts, Ivora can switch a team to enterprise invoicing (billing_mode: "enterprise"). Only Ivora sets it, together with the team's terms. The team then needs no card: its status is enterprise.

Each month's invoice is computed the same way, but it is sent rather than charged. It is due invoice_terms.net_terms_days after it is sent (30 by default), shown as due_date, and its hosted_invoice_url is Stripe's page to view, download or pay it. The invoice carries the team's legal name, address, tax IDs and PO number, and Ivora's memo and footer. Stripe emails it to the first of invoice_terms.billing_emails.

An enterprise invoice can be paid by:

Bank transfer: send an ACH credit or wire in US dollars to the account in bank_transfer.financial_addresses. That account is the team's own, so the payment is matched to its invoices automatically. From a Canadian bank, send a USD wire to the swift address; your bank converts any Canadian dollars.
ACH Direct Debit (a US bank account): connect it (below) and it is debited automatically on the due date. A debit takes a few business days to settle, during which the invoice shows payment_processing: true.
Pre-authorized debit (a Canadian bank, when Ivora set the team's bank_country to ca): connect a US dollar account at the Canadian bank. The debit is in US dollars; a Canadian dollar account would refuse it days later. Invoices list it once the account is verified.
Card, when Ivora allows it for the team. If Ivora has Stripe's currency conversion turned on, a payer in Canada can pay the card in Canadian dollars on the invoice page: Stripe converts and adds its conversion fee (2–4%) to the CAD amount. Stripe offers this only on invoices without pre-authorized debit.

The team's billing members connect the bank account from the team routes: POST /v1/teams/{team_id}/billing/bank-account/setup returns a Stripe-hosted page that verifies the account (instantly through the bank, or with two small deposits) and accepts the debit mandate; nothing is charged. Then call POST .../bank-account/sync. bank_account.status is verified, or pending_verification until the deposits are confirmed. DELETE /v1/teams/{team_id}/billing/bank-account removes it. With a verified account, invoice_terms.collection is auto_debit; otherwise invoice_only.

The billing contacts, legal name, PO number and bank transfer instructions are shown only on GET /v1/teams/{team_id}/billing, to the team's signed-in owners, admins and billing members. A project's billing profile, which billing:read API keys can read, shows the mode, bank_account and invoice_terms without them.

An unpaid enterprise invoice shows overdue: true and days_overdue after its due date, and Ivora's billing team is alerted. Being overdue never suspends the team by itself: the contract decides, and only Ivora staff can suspend a team. A suspended team's new CSMS setup and control answer 402 billing_suspended. Charging, stops and reads are never affected.

Ivora can also set a minimum monthly commitment for a team. A month whose usage, after any discount, is below it is raised to the minimum by a minimum monthly commitment line (minimum_topup_minor).

Every rate, amount and invoice is in US dollars (currency: "usd"), for Canadian teams too. Only a card payment can be converted to Canadian dollars by Stripe; bank transfers and debits are always in US dollars.

Add or replace the team's card

A signed-in tenant admin, or the team's owner, admin or billing member, manages the card in the Platform; API keys cannot. A tenant admin of any project of the team can manage the team's card, from that project's routes.

POST /v1/tenants/{tenant_id}/billing-profile/payment-method/setup returns a Stripe-hosted page on Ivora's own Stripe account. It saves a card for the team without charging it and returns to the Platform's billing page, which Ivora chooses.
POST /v1/tenants/{tenant_id}/billing-profile/payment-method/sync records the saved card. It is safe to repeat. A new card replaces the team's previous one, which is removed from Stripe.
DELETE /v1/tenants/{tenant_id}/billing-profile/payment-method removes the team's card, for every project of the team.

From the team

The same billing is also reachable for the whole team, without picking a project. These routes are for the team's signed-in owners, admins and billing members (and Ivora staff); API keys cannot use them. A member limited to some projects still sees the whole team's billing, because the card, invoices and usage belong to the team.

GET /v1/teams/{team_id}/billing: the team's status, payment_method, grace_ends_at, past_due_since, discount_percent, and every project with its rate_cents_per_kwh, rate_source and current_month.
GET /v1/teams/{team_id}/billing/invoices and GET /v1/teams/{team_id}/billing/usage: the same invoices and month estimate as the project routes above.
POST /v1/teams/{team_id}/billing/payment-method/setup, then POST .../payment-method/sync; DELETE /v1/teams/{team_id}/billing/payment-method removes the card.

The team ID is the id in GET /v1/me/teams.

What needs a payment method

Without a usable team card, waiver, 100% discount or grace period, or 14 days after a failed invoice payment, these return 402 payment_method_required:

creating stations and locations;
creating API keys with CSMS scopes;
station commands other than stop and unlock;
smart charging writes: setting or clearing charging profiles and session caps;
creating bills and external charging sessions.

These are never blocked: OCPP traffic from your chargers, charging sessions already running, every read, stopping a session or unlocking a connector, starting a bill or external session that already exists (it was checked when it was created, so a driver's card hold is never stranded), and finalizing, capturing, releasing or refunding existing bills. Drivers are never stranded.

A retry of a gated request with the same Idempotency-Key returns the original result, even if the team's payment method has lapsed since.

Every tenant that existed when the fee was introduced has a team of its own with 30 days of grace, shown in grace_ends_at. Teams created afterwards add a card first. An expired card does not count. Ivora staff can waive a team's requirement, set its discount, extend its grace period, set its rate or a project's rate, and link projects into one team; every change is recorded with who made it and why.