API reference

Ivora API

One tenant-scoped REST API for charger management, charging and billing support. Requests and responses are JSON over HTTPS; every public endpoint is listed by resource on the left.

Base URL: https://api.ivoracharge.com (production; Ivora grants access to approved tenants). Generated from the OpenAPI contract, version 1.0.0, as of 2026-10-06. Download the published OpenAPI document.

Authentication

Send a tenant-scoped API key as a bearer token: Authorization: Bearer iv_live_…. Production keys start with iv_live_. A signed-in user creates keys with the scopes an application needs in Developer tools; station and billing keys bind to that user's tenant. Keys cannot onboard users or issue other keys.

Keep keys on your application server. Start with GET /v1/access to read your tenant ID and permissions, then use the tenant ID in resource paths.

Authenticated request

curl --fail-with-body https://api.ivoracharge.com/v1/access \
  -H "Authorization: Bearer $IVORA_API_KEY"

Errors

Errors use conventional HTTP status codes and one JSON shape. Branch on the stable error.code, not on the message. Include request_id when you contact Ivora. Rejected charger operations repeat the same shape in result.error.

Error object

errorErrorDetailRequired
Child attributes
- codestringRequired
  Stable machine-readable condition, for example station_offline or idempotency_key_reused. Generic codes (not_found, conflict, invalid_request) remain for conditions without a specific code.
- messagestringRequired
- detailsobject | null
  Optional structured context such as operation_id or resource_id.
request_idstringRequired

Status codes

401
Missing, malformed, revoked or wrong-environment credential.
403
The key lacks the required scope or is not bound to this tenant.
404
The resource does not exist in your tenant.
409
The request conflicts with current state, for example idempotency_key_reused or station_offline.
422
The request failed validation; details name the invalid fields.
429
Rate limited. Wait for the Retry-After header before retrying.
502
An upstream service (charging core or payment provider) failed.
503
Temporarily unavailable, or outcome_unknown: reconcile before retrying.

Error response · 409

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was used with a different request body.",
    "details": null
  },
  "request_id": "req_0123456789abcdef"
}

Idempotency, units and retries

Keep tenant API keys on your application server. Your app controls host/guest permissions and bookings within its granted fleet.
Station reads need stations:read; provisioning and charger displays need stations:write; commands need stations:control. Bills and payments use billing:read / billing:write. Bill start also needs stations:control. External session creation/start opts in with settlement:write; reporting requires that scope and never executes a payment. Key management requires a signed-in workspace owner.
Charging/billing writes that declare Idempotency-Key require 8–128 printable characters. Generate a unique key per operation and reuse it with the same body after a timeout.
Creating a location, station or tariff returns 201 with the resource and its ID; add external_reference to find it by your own identifier. Charger-bound writes return a 202 operation: poll it, or subscribe to operation.completed under Webhooks and events. Reconcile an unknown charger outcome before issuing another command. Unknown payment operations older than 23 hours require operator reconciliation.
Errors are {"error": {"code", "message", "details"}} with stable codes such as station_offline or idempotency_key_reused; rejected operations repeat the shape in result.error.
Core energy is kWh and every energy field also carries integer energy_wh; sandbox increments are Wh; tariff and payment amounts are integer minor currency units. Bills fix the tariff and final amount; payment clients cannot choose a different capture amount.

Read the retries and units guide →

Idempotent create

curl --fail-with-body -X POST https://api.ivoracharge.com/v1/tenants/1042/locations \
  -H "Authorization: Bearer $IVORA_API_KEY" \
  -H "Idempotency-Key: location-property-1001" \
  -H "Content-Type: application/json" \
  -d '{"name": "Harbor Loft", "external_reference": "property:1001"}'

Choose a workflow

Start with the settlement flow comparison and architecture diagrams. The guides distinguish managed payments, application-managed processors, existing driver settlement and free/simulated charging. External charging sessions allow your backend to integrate its own processor now. Self-service managed-adapter registration remains planned.

Business profiles, free-charging eligibility/passwords, QR cards and checkout presentation belong to the consuming application and its database. The shared API handles charger operations, trusted usage and billing support. It also keeps the QR a charger's own screen shows as desired state; your application chooses that URL and serves its page.

Task	Reference sections	Order of calls
Register a charger	Locations → Stations	Create location → register station (both return the resource) → set connection credentials → read connector state
Show a QR on a charger screen	Stations → Charger displays	Read the station's `display` field → set each EVSE's display → watch `delivery.state` or `display.delivery_changed`; print the QR where the state is `unsupported`
Stop polling	Webhooks and events	Register an HTTPS endpoint → verify the signed test delivery → consume operation, session, bill and display events
Paid charging	Tariffs and bills → Payments → Charging and operations	Create bill → authorize payment → follow checkout → confirm authorization → start bill → observe transaction → stop → finalize bill → capture
Application-managed processor	External charging sessions	Authorize in your backend → create session → attest funding/start → observe/stop → finalize → capture in your backend → optionally report outcome
Release or refund	Payments	Release an unused authorization; refund a captured payment
Try without hardware	Workspaces → Sandbox charging	Create workspace → start a simulated session → advance metering → stop and settle

For payment-adapter testing without hardware, create a bill with source: simulated and finalize it with energy_wh. Physical bills use source: csms and a completed transaction_id.

Try it

Requests from these pages are off until the production API at https://api.ivoracharge.com is public. Every endpoint page has curl, Node.js and Python samples to run from your application server.

Resources

Getting started

get Discovery
get Health
get Public Config
get Capabilities

Access and API keys

post Retrieve the charging tenant of your access grant
get Keys
post Create Key
delete Revoke

+1 more

Payment account

get Read the tenant's payment account
post Create a Stripe onboarding link
post Disconnect the tenant's payment account

Locations

get List tenant locations
post Create a tenant charging location and return it
get Read one location
patch Update a location's details

Stations

get List tenant charging stations
post Register a station and return it
get Read station and connector state
patch Move a station to an owned location

+3 more

Charger displays

get List a station's charger displays
get Read a charger display and its delivery
put Set the QR a charger screen shows
delete Stop maintaining a charger display

+2 more

OCPP domains

get List custom OCPP hostnames and DNS/TLS readiness
post Prepare a tenant OCPP domain and its two DNS records
get Read one OCPP domain setup
delete Disable this domain for new charger connections

+2 more

Charging and operations

post Dispatch start, stop, reset, unlock or availability
get Read charging usage and realized billing
get Inspect an operation without redispatching it
post Start charging after adapter authorization

Tariffs and bills

get Read tenant billing tariffs
post Create a core tariff version and return it
get Read one tariff
get List tenant bills

+4 more

Payments

get List configured payment adapters
post Create a hosted authorization for a bill
get Synchronize payment status with the provider
post Capture exactly the immutable bill amount

+2 more

Webhooks and events

get List webhook endpoints
post Register an HTTPS endpoint for tenant events
get Read one webhook endpoint
delete Disable a webhook endpoint

+3 more

External charging sessions

get Find externally funded sessions
post Create an externally funded charging session
get Observe session usage, bill and reported settlement
post Start using application-confirmed funding

+5 more

Workspaces

get Me
post Workspace
put Branding

72 operations in 13 groups.