Charges

This section explains the lifecycle of a charge, the meaning of each timestamp field, and how to interpret charge states in the Monta API.

Charge Lifecycle Overview

A charge progresses through several phases from initiation to completion:

Cable Plugged In → Charge Created → Starting → Charging → Stopping → Completed

Each phase is tracked by specific timestamp fields and reflected in the charge state.

Timestamp Fields

Field	Description
`createdAt`	When the charge record was created in the system
`cablePluggedInAt`	When the cable was physically connected to the vehicle
`startedAt`	When the charge session began initializing
`stoppedAt`	When the charge session stopped
`completedAt`	When the charge was finalized and billing completed
`failedAt`	When the charge failed (if applicable)

Timestamp Sequence

For a successful charge, timestamps follow this order:

createdAt ≤ cablePluggedInAt ≤ startedAt < stoppedAt ≤ completedAt

Nullable Timestamps

Most timestamp fields can be null. Here's what null values indicate:

Field	When Null
`cablePluggedInAt`	Cable not yet connected, or connection not detected
`startedAt`	Charge session has not begun initializing
`stoppedAt`	Charge is still active, or auto-completed without explicit stop
`completedAt`	Charge has not been finalized
`failedAt`	Charge did not fail

Charge States

The state field indicates the current phase of a charge:

State	Description
`reserved`	Charge point reserved for the user
`paying`	Payment authorization in progress
`scheduled`	Charge scheduled for a future time (smart charging)
`starting`	Charge initializing, waiting for energy flow
`charging`	Energy actively flowing to vehicle
`paused`	Charging temporarily paused (includes EV or EVSE suspension)
`stopping`	Stop command sent, waiting for confirmation
`stopped`	Charge stopped, awaiting finalization
`releasing`	Cable lock being released
`released`	Cable released
`completed`	Charge finalized (terminal state)

State Categories

Pre-charging states (energy not yet flowing):

reserved, paying, scheduled, starting

Active states (charge in progress):

charging, paused

Ending states (charge winding down):

stopping, stopped, releasing, released

Terminal state (no further transitions):

completed

Common Scenarios

Successful Charge

{
  "state": "completed",
  "createdAt": "2026-01-22T10:00:00Z",
  "cablePluggedInAt": "2026-01-22T10:00:05Z",
  "startedAt": "2026-01-22T10:00:10Z",
  "stoppedAt": "2026-01-22T11:30:00Z",
  "completedAt": "2026-01-22T11:30:05Z",
  "failedAt": null,
  "failureReason": null
}

Active Charge (Currently Charging)

{
  "state": "charging",
  "createdAt": "2026-01-22T10:00:00Z",
  "cablePluggedInAt": "2026-01-22T10:00:05Z",
  "startedAt": "2026-01-22T10:00:10Z",
  "stoppedAt": null,
  "completedAt": null,
  "failedAt": null,
  "failureReason": null
}

Cable Plugged, Waiting to Start

{
  "state": "starting",
  "createdAt": "2026-01-22T10:00:00Z",
  "cablePluggedInAt": "2026-01-22T10:00:05Z",
  "startedAt": "2026-01-22T10:00:10Z",
  "stoppedAt": null,
  "completedAt": null,
  "failedAt": null,
  "failureReason": null
}

Failed Charge

{
  "state": "completed",
  "createdAt": "2026-01-22T10:00:00Z",
  "cablePluggedInAt": null,
  "startedAt": null,
  "stoppedAt": null,
  "completedAt": "2026-01-22T10:00:05Z",
  "failedAt": "2026-01-22T10:00:04Z",
  "failureReason": "Failed to start: Connector unavailable"
}

Auto-Completed Charge (Vehicle Reached Full)

When a vehicle automatically stops charging (e.g., battery full), stoppedAt may be null:

{
  "state": "completed",
  "createdAt": "2026-01-22T10:00:00Z",
  "cablePluggedInAt": "2026-01-22T10:00:05Z",
  "startedAt": "2026-01-22T10:00:10Z",
  "stoppedAt": null,
  "completedAt": "2026-01-22T11:30:00Z",
  "failedAt": null,
  "failureReason": null
}

Understanding Failed Charges

A charge can fail at various points in its lifecycle. Failed charges have:

failedAt timestamp set
failureReason containing the error description
state set to completed (terminal state)

Important: The state field shows completed for failed charges because completed represents a terminal state where no further processing occurs. Always check failedAt and failureReason to determine if a charge failed.

Common Failure Reasons

Failure Reason	Description
`Failed to start: Connector unavailable`	Connector was occupied, offline, or in an error state
`Failed to start: Transaction timeout`	Charge point did not respond in time
`Failed to start: Authorization failed`	Payment or authentication failed

Detecting Failed Charges

To determine if a charge failed, check for the presence of failure fields:

function isChargeFailed(charge) {
  return charge.failedAt !== null || charge.failureReason !== null;
}