API reference

Providers, accounts and users

Ownership on the platform rests on three entities: the Provider, the Account and the User. Everything else is owned somewhere beneath them.

Provider

A Provider is the top-level tenant, a "super organisation". Every object on the platform is owned by a Provider. A Provider is usually one of:

  • a Private Label: a business running the platform under its own brand and onboarding its own customers as Accounts,
  • a single operator: a corporate or infrastructure owner using the platform only for its own charging, with Accounts mirroring its internal structure and no external customers,
  • an eMSP that mainly issues charge cards.

The CPOs that run charging stations usually join a Provider as Accounts, not as Providers of their own.

Providers are created and configured by your Road account manager to fit the business. For complex organisations, sub-providers let a super organisation sit over several underlying entities.

Account

An Account is the central organisational unit, owned by a Provider. It is the entity that actually owns the working parts of the platform: Locations and charging stations, Charge Cards and their Tokens, and the Sessions run against them. It is also the entity the platform bills, and the entity that receives reimbursements.

An Account is deliberately flexible. It can represent:

  • a customer of a Private Label (where the Provider is a reseller), or
  • an internal structure of a corporate, such as a department, branch or regional office.

Because the Account holds both the locations and the tokens, it carries the financial responsibility: the socket fees for its locations, and the cost of the charging sessions its users run. In most cases an Account is also reimbursed for sessions on the stations it owns, though some setups differ, home-charging reimbursement for example.

User

A User is an individual login belonging to an Account. An Account can have many Users, so a team can manage charging together while billing and contractual responsibility stay with the Account.

A User's roles set what they can do, from full administrative control (billing, cards, locations) down to limited access (ordering a card, viewing their own sessions). Roles are assigned at two levels:

  • Account roles apply within one Account, for the people who run its charging.
  • Provider roles apply across the tenant. There is no separate directory of administrators: a Provider administrator is simply a User carrying provider-level roles.

Through their roles, a User can order and manage Charge Cards and Tokens, create and manage Locations and their charging stations, monitor charging sessions and their costs, and administer Account settings.

Users act, but the Account owns: whatever a User creates or spends is owned and settled at the Account level.

Getting people onto an Account

People reach an Account in three ways:

  • They sign up. Where you run a white-label dashboard or app, a customer can register through the web sign-up flow, which creates their Account and User for them. This is the usual path for consumer-facing setups.
  • You provision them. Your own system creates the Accounts and Users and supplies their details. This suits a Private Label running its own signup, or anyone who runs their own sign-in and mirrors users onto Road. See the Accounts and Users endpoints.
  • You invite them. Road emails the person, and they set their own password and finish their profile, becoming a User when they accept. Reach for this when you would rather someone onboard themselves than hold their credentials for them. See Invites.

There is also a focused invite for bringing a customer onto a station you have already configured: Road emails them to set up their account for that charging station and start using it.

Billing and reimbursement

An Account has two sides to its money, and they are deliberately separate:

  • Billing is how the Account pays: its billing address and VAT details, whether collection is automatic or manual, and the bank details used to collect. This covers what the Account owes, its usage and any subscriptions.
  • Credit billing is how the Account gets paid: the bank details Road uses to reimburse a CPO for the energy its stations deliver.

Many Accounts have both. A customer that both runs stations and issues cards pays for the charging its cards use through billing, and is reimbursed for the charging its stations deliver through credit billing.

Setting up the payment method a customer actually pays with, a card or a direct-debit mandate, happens through the dashboard's payment flow rather than by handing card details to the API. The billing fields themselves sit on the Accounts endpoints.

Account tiers

An account tier bundles a set of platform features and is priced by a billing plan. Putting an Account on a tier sets which features it has and what it pays to run on the platform. Tiers let a Provider offer levels, a basic tier and a richer one, say, and move Accounts between them as their needs change. The available tier plans are in the Billing plans reference.

Matching your records with externalId

Both Accounts and Users can carry an externalId, your own reference for them. Road keeps its own IDs; the externalId lets you line the two up without threading Road's IDs through your systems. It also does double duty for single sign-on: when SAML or OIDC is enabled, Road matches a sign-in to the User whose externalId equals the identifier your identity provider sends. See Single Sign-On.

Over their lifetime

Accounts and Users can be searched, updated and retired as things change. Removing an Account is a soft delete, so it can be restored if you need it back. The full set of operations, and the exact fields, live in the API reference.