Integration

This pathway is for battery manufacturers (OEMs) who run their own cloud platform and want their users to be able to join the Axle VPP. You send us telemetry, we handle optimisation, market participation and customer relations. We’ll send dispatch instructions to an endpoint you provide for you to execute on your own fleet. The integration has three parts:

Onboarding
Telemetry
Dispatch

1. Onboarding

Each battery needs a site_id and asset_id in Axle’s system before you can send telemetry or receive dispatch for it — these are the identifiers used throughout the rest of the integration. There are two ways to get there. Pick one. They’re alternatives rather than steps: either you create the site and asset yourself through our API, or Axle creates them during signup and hands you the identifiers. Doing both will give you two sets of identifiers for one battery.

What we mean by a “battery”. Axle treats a battery as a complete battery system — the battery, its inverter and its meter. If a site has several battery units behind a single system, register them as one asset with the combined capacity.

Through your app
Through Axle's signup flow

If you already collect address, consent and asset details yourself, call Axle’s onboarding API directly.

Onboard site and asset

Example request

{
  "site": {
    "email": "example@example.com",
    "mpan": "1234567890123",
    "postcode": "SW1A 1AA",
    "street_address": "10 Downing Street",
    "gave_boundary_meter_consent_at": "2025-01-01T12:00:00Z"
  },
  "asset": {
    "external_id": "battery-001",
    "type": "battery",
    "properties": {
      "power_kw": 5.0,
      "capacity_kwh": 13.5
    }
  },
  "dispatch_consent": {
    "dispatch_methods": ["vpp_limited_control"]
  }
}

Your backend authenticates as described in Authentication.

Use vpp_limited_control in the dispatch_methods array. That’s event-only mode, which is what the integration on this page delivers today — full_asset_schedule_control isn’t yet available over the dispatch webhook.You don’t need to send us tariff details either way. We collect those from the customer ourselves, and they can opt into full optimisation later from their Axle account pages.

If you’d rather not build a signup UI, your customers can sign up on a flow Axle hosts and connect their battery by signing in with their existing account on your platform. Your platform acts as the OAuth2 provider (authorisation server) and Axle is the client — a standard authorisation-code flow, the same way we integrate with manufacturers today.

Customer starts on Axle's signup page

The customer lands on Axle’s signup page and begins signup. Axle creates the site at this point.

Customer selects your brand and connects

The customer picks your brand as their battery manufacturer and clicks “Connect”. Axle redirects them to your OAuth2 authorisation page with client_id, redirect_uri, scope and state.

Customer signs in with you

The customer signs in with their existing account and authorises access — no Axle password needed. You redirect them back to Axle’s callback with an authorisation code, which Axle exchanges for an access token server-to-server at your token endpoint.

Axle identifies the battery

Axle calls your device-list API with the access token to find the customer’s devices. The customer confirms their battery and completes address, MPAN and consent — staying on Axle throughout, finishing on an Axle-hosted welcome page. Axle creates the asset with your device serial recorded against it.

Axle registers the asset with you

Axle sends you a vpp:asset:registered webhook, signed and delivered like any other. The payload carries the asset_id you’ll use for Telemetry and Dispatch, together with the device serial so you can match it to your customer:

{
  "site_id": "9f2b7a13-4c8d-4e21-9a76-5d1c3b8e0f42",
  "asset_id": "3c361164-5187-4b4b-8e8a-7b3f67c4d5a8",
  "device_serial": "OEM-SERIAL-12345",
  "registered_at": "2026-08-11T14:02:11.301045Z"
}

Wait for this webhook rather than calling the onboarding API yourself — on this pathway we own creating the site and asset, and an asset_id you mint elsewhere won’t be one we recognise.

What you need to provide

A standard OAuth2 authorisation-code flow: a hosted sign-in page and a token endpoint
A client_id and client_secret issued to Axle
Axle’s redirect URI whitelisted: https://api.axle.energy/vpp/oauth/{provider}/callback
A scope granting access to the customer’s devices
A device-list API returning the customer’s devices (serial, power/capacity) for a given access token
A webhook endpoint that accepts the asset registration shown above

Identifiers are scoped to one environment and one organisation. A sandbox asset_id won’t resolve against production, a production token won’t reach sandbox assets, and no other organisation can see yours. If telemetry comes back with an unknown asset_id, that mismatch is the first thing to check.

2. Telemetry

Send regular readings for each battery so we can optimise it and verify delivery. Which readings we need depends on the mode the battery runs in:

Mode	Readings we need
Event-only	`battery_state_of_charge_pct` (0–100) and `boundary_import_kw`
Fully optimised	The two above, plus `battery_inverter_import_kw` and `solar_power_kw`

boundary_import_kw is grid import and export at the site boundary. Grid power is bidirectional, so the sign tells us the direction: positive = import from the grid, negative = export to the grid. Push readings to the readings endpoint, which lists every accepted label and its sign convention.

Cadence

Send readings every 5 minutes. Ordinary scheduler and network jitter around that is fine, we don’t need the interval to be exact, and we’d rather have a steady 5-minute snapshot than raw per-minute telemetry.

Timestamps

Every reading carries a start_timestamp and an end_timestamp, and which of the two forms you use depends on the reading:

Form	Timestamps	Readings
Instantaneous — a spot value at a point in time	`start_timestamp` = `end_timestamp`	All power readings (`boundary_import_kw`, `battery_inverter_import_kw`, `solar_power_kw`), `battery_state_of_charge_pct`, `battery_stored_energy_kwh`, and the lifetime meter registers `boundary_lifetime_import_energy_kwh` and `boundary_lifetime_export_energy_kwh`
Interval — energy accumulated over a window	`start_timestamp` < `end_timestamp`	Interval energy such as `provisional_consumption_kwh`

The lifetime meter registers are cumulative, but they’re still instantaneous readings: each one is the register’s value as read at a single moment. Send them with matching timestamps rather than spanning back to the previous reading.

Send telemetry

Push battery and boundary readings to Axle.

If pushing readings doesn’t suit your platform, we can also pull readings from custom endpoints you provide — get in touch to discuss your setup.

3. Dispatch

During a grid event we send a dispatch instruction to a webhook URL you provide. Each instruction covers a single event and sets a target power for every affected asset over a fixed window. You supply the webhook URL when you set up your integration — get in touch to register it.

{
  "event_id": "eab8c867-7c4d-4116-a587-02c9d1f13a16",
  "issued_timestamp": "2026-06-29T17:02:37.448917+00:00",
  "start_time": "2026-06-30T20:30:00+00:00",
  "end_time": "2026-06-30T21:30:00+00:00",
  "assets": [
    { "asset_id": "3c361164-5187-4b4b-8e8a-7b3f67c4d5a8", "power_kw": -6.915 },
    { "asset_id": "1a161164-5187-4b4b-8e8a-7b3f67c4d5a8", "power_kw": -4.915 }
  ]
}

power_kw uses the same sign convention as telemetry: positive = charge (import into the battery), negative = discharge (export). Apply the target power to each asset for the window between start_time and end_time. The target power applies at the inverter. We dispatch at the inverter’s rated power, and we account for the fact that household load can limit the power the battery actually delivers. If no power rating was recorded for an asset at registration, we fall back to 5 kW, so send power_kw when you register the battery.

Timing

We send the instruction 10 minutes before the event starts. That’s deliberate, and it shapes the rest of the contract. We only issue an instruction for an event that is definitely going ahead, which means we never need to withdraw one: there’s no cancellation webhook, and an instruction you’ve received will not be amended. The trade-off is that you need to be able to act on a dispatch within a few minutes of receiving it. If that’s too tight for your cloud-to-device path, get in touch and we can look at extending it. Windows always align to 30-minute boundaries, in ISO-8601 UTC and never with microseconds. Each instruction covers a single continuous window — most commonly an hour, sometimes 30 minutes or two hours — and never several segments.

You get one instruction per grid event. We don’t re-send it during the event, so if execution fails at your end nothing re-asserts the setpoint. Delivery retries are a separate matter: if your endpoint returns a 5xx or times out we’ll retry that delivery, carrying the same envelope id.

Confirming delivery

Return a 2xx and keep telemetry flowing. That’s all we need — there’s no status callback to implement, and we use your 5-minute readings to verify what was delivered and to settle the event, which lands two days afterwards. The same goes for shortfalls. If a local limit gets in the way — low state of charge, thermal derating, an anti-backflow cap, or a battery that’s simply offline — you don’t need to report it. The readings will show what the battery actually did.

Dispatch webhook

Full schema for the dispatch instruction we send to your webhook.

If you already have your own dispatch API, we can work with custom dispatch endpoints instead of the webhook above — get in touch to discuss your setup.

Important points

Customers should be able to override dispatch instructions at any time.
The battery should return to its original mode of operation after the dispatch event has finished

Testing your integration

Build against the sandbox at https://api-sandbox.axle.energy before you go near production. Identifiers, tokens and webhook signing keys are all distinct between the two.

Get sandbox credentials

Get in touch and we’ll set up a sandbox account, then exchange your credentials for a token as described in Setting up an environment.

Send telemetry against a sandbox asset

Onboard a battery, or ask us to provision one, and push readings to POST /data/readings.

Send us the URL you want dispatch instructions delivered to, and we’ll register it and issue a signing key. We start in sandbox and move to production once you’ve signed the integration off.

Trigger a test dispatch

Call POST /webhooks/test to have us deliver a vpp:dispatch:requested event to your registered endpoint, through the same signing and retry machinery as a real one. See Testing your endpoint for the request format, how to point a test at one of your real assets, and how to tell a test event from a real one.

Next steps

Webhooks

The delivery contract: envelope, signature verification, responses and retries

Site and asset lifecycle

How sites and assets move through the platform, and how to handle a customer opting out

Home

Assets

Core workflows

EV Charging

Batteries & Heating

1. Onboarding

Onboard site and asset

2. Telemetry

Cadence

Timestamps

Send telemetry

3. Dispatch

Timing

Confirming delivery

Dispatch webhook

Important points

Testing your integration

Next steps

Webhooks

Site and asset lifecycle

​1. Onboarding

Onboard site and asset

​What you need to provide

​2. Telemetry

​Cadence

​Timestamps

Send telemetry

​3. Dispatch

​Timing

​Confirming delivery

Dispatch webhook

​Important points

​Testing your integration

​Next steps

Webhooks

Site and asset lifecycle

1. Onboarding

What you need to provide

2. Telemetry

Cadence

Timestamps

3. Dispatch

Timing

Confirming delivery

Important points

Testing your integration

Next steps