CapacitorDocs
HomeSign inGet Started
Getting StartedTutorialAuthenticationChargersId TagsTransactionsWebhooksCommandsWebSocketBillingErrors

Tutorial: Your First Charging Session

This guide walks you through the complete flow — from registering an EV charger to checking how much energy was delivered. By the end, you'll have started and stopped a real charging session using the Capacitor API.

Prerequisites: A Capacitor account and an API key.

What is a Charge Box ID?

Every OCPP charger has a unique identifier called the chargeBoxId. This is typically the charger's serial number, which you can find on a label or sticker on the charger body, or in its configuration interface.

You choose this value when registering the charger with Capacitor — it must match exactly what the charger sends in its WebSocket connection. For example: ABB-T2-00412, WALLBOX-SN-7891, CP-OFFICE-01.

The chargeBoxId must be unique within your organisation.

Step 1 — Register the charger

Tell Capacitor about your charger by creating a charger resource. The response includes the WebSocket URL you'll configure on the physical charger.

POST/api/v1/chargers
Register a charger
bash
curl -X POST https://api.capacitor.live/api/v1/chargers \
  -H "X-API-Key: cap_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "chargeBoxId": "CP-OFFICE-01",
    "name": "Office Parking Charger",
    "location": "Building A, Parking Level 1"
  }'
Response — 201 Created
json
{
  "chargeBoxId": "CP-OFFICE-01",
  "name": "Office Parking Charger",
  "location": "Building A, Parking Level 1",
  "status": "offline",
  "connectionUrl": "wss://api.capacitor.live/ocpp/CP-OFFICE-01",
  "instructions": {
    "message": "Configure your charger to connect to the WebSocket URL",
    "url": "wss://api.capacitor.live/ocpp/CP-OFFICE-01",
    "protocol": "ocpp1.6"
  }
}

Step 2 — Connect the charger

Open your charger's configuration interface and set the OCPP backend URL to the connectionUrl from the registration response. Once configured, the charger connects via WebSocket and sends a BootNotification automatically.

If the charger doesn't come online, double-check that the WebSocket URL matches exactly and that the charger supports OCPP 1.6J.

Step 3 — Verify the charger is online

Before starting a session, confirm the charger has connected successfully. List your chargers to see an overview, then fetch the specific charger to check its status.

GET/api/v1/chargers
List all chargers
bash
curl https://api.capacitor.live/api/v1/chargers \
  -H "X-API-Key: cap_live_..."
Response
json
{
  "chargers": [
    {
      "chargeBoxId": "CP-OFFICE-01",
      "name": "Office Parking Charger",
      "status": "online",
      "isOnline": true,
      "lastHeartbeat": "2025-01-15T10:32:00Z"
    }
  ]
}

You can also fetch a single charger directly to confirm it's online:

GET/api/v1/chargers/{chargeBoxId}
Get a specific charger
bash
curl https://api.capacitor.live/api/v1/chargers/CP-OFFICE-01 \
  -H "X-API-Key: cap_live_..."
Response
json
{
  "chargeBoxId": "CP-OFFICE-01",
  "name": "Office Parking Charger",
  "status": "online",
  "isOnline": true,
  "lastHeartbeat": "2025-01-15T10:32:00Z"
}
Make sure isOnline is true before proceeding. If the charger is offline, commands like RemoteStartTransaction will fail.

Step 4 — Check connector status

Connectors are the physical plugs on a charger, numbered from 1. Most chargers have one or two connectors. Check the status of connector 1:

GET/api/v1/chargers/{chargeBoxId}/connectors/{connectorId}/status
Check connector status
bash
curl https://api.capacitor.live/api/v1/chargers/CP-OFFICE-01/connectors/1/status \
  -H "X-API-Key: cap_live_..."
Response
json
{
  "chargeBoxId": "CP-OFFICE-01",
  "connectorId": 1,
  "status": "Available"
}

Status reference:

StatusMeaning
AvailableReady for use, no cable plugged in
PreparingCable plugged in, waiting for session to start
ChargingActively delivering energy
FinishingSession complete, cable still connected
FaultedCharger has reported an error

Step 5 — Plug in the cable

Plug the charging cable into the vehicle. The connector status changes from Available to Preparing.

Connector status after plugging in
json
{
  "chargeBoxId": "CP-OFFICE-01",
  "connectorId": 1,
  "status": "Preparing"
}
A RemoteStartTransaction will be rejected if the connector is not in Preparing status. Make sure the cable is plugged in before starting a session.

Step 6 — Start a charging session

With the cable plugged in, start a charging session remotely. The idTag identifies who is charging — this can be an RFID tag ID, a user ID from your system, or any string you use to track sessions.

POST/api/v1/transactions/start
Start a charging session
bash
curl -X POST https://api.capacitor.live/api/v1/transactions/start \
  -H "X-API-Key: cap_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "chargeBoxId": "CP-OFFICE-01",
    "connectorId": 1,
    "idTag": "USER-001"
  }'
Response — 202 Accepted
json
{
  "status": "Accepted",
  "message": "RemoteStartTransaction request sent to charger"
}
The charger may take a few seconds to begin charging after accepting the request.

Step 7 — Verify charging is in progress

Check the connector status — it should now show Charging. Then find the active transaction:

GET/api/v1/transactions?chargeBoxId={chargeBoxId}&status=in_progress
Find the active transaction
bash
curl "https://api.capacitor.live/api/v1/transactions?chargeBoxId=CP-OFFICE-01&status=in_progress" \
  -H "X-API-Key: cap_live_..."
Response
json
{
  "transactions": [
    {
      "transactionId": "txn_abc123",
      "chargeBoxId": "CP-OFFICE-01",
      "connectorId": 1,
      "idTag": "USER-001",
      "status": "in_progress",
      "energyDelivered": 2.45,
      "startTime": "2025-01-15T10:35:00Z"
    }
  ]
}

Save the transactionId — you'll need it to stop the session.

Step 8 — Stop the charging session

When you're ready, stop the session using the transaction ID:

POST/api/v1/transactions/{transactionId}/stop
Stop the session
bash
curl -X POST https://api.capacitor.live/api/v1/transactions/txn_abc123/stop \
  -H "X-API-Key: cap_live_..."
Response — 202 Accepted
json
{
  "status": "Accepted",
  "message": "RemoteStopTransaction request sent to charger"
}

Step 9 — Check the results

Once the charger confirms the stop, fetch the completed transaction to see the final results:

GET/api/v1/transactions/{transactionId}
Get transaction details
bash
curl https://api.capacitor.live/api/v1/transactions/txn_abc123 \
  -H "X-API-Key: cap_live_..."
Response
json
{
  "transactionId": "txn_abc123",
  "chargeBoxId": "CP-OFFICE-01",
  "connectorId": 1,
  "idTag": "USER-001",
  "status": "completed",
  "startTime": "2025-01-15T10:35:00Z",
  "stopTime": "2025-01-15T11:50:00Z",
  "energyDelivered": 18.73,
  "durationMinutes": 75,
  "meterStart": 10000,
  "meterStop": 28730,
  "stopReason": "Remote",
  "remoteStarted": true
}

Key fields:

FieldDescription
energyDeliveredTotal energy in kWh
durationMinutesSession length in minutes
meterStart / meterStopCharger meter readings in Wh
stopReasonWhy the session ended (Remote, Local, EVDisconnected, etc.)
remoteStartedWhether the session was started via the API

Troubleshooting

Charger won't connect?

  • Verify the WebSocket URL matches exactly
  • Check that charger supports OCPP 1.6J (not 1.5 or 2.0)
  • Confirm chargeBoxId in charger config matches registration

RemoteStart fails?

  • Confirm connector status is "Preparing" (cable must be plugged in)
  • Verify charger is online (isOnline: true)
  • Check that connectorId exists on the charger

Transaction not starting?

  • Some chargers require authorization first (use Authorize endpoint)
  • Check charger logs for error codes
  • Verify idTag format matches charger requirements