Change a session's metadata

Path parameters

• tenant_idintegerRequired
• session_idstringRequired

Headers

• idempotency-keystringRequired

Request body

• metadataobject | nullRequired
  Your own key/value pairs (strings), such as a site host or a contract ID: at most 50 keys of 1-40 characters of A-Z, a-z, 0-9, underscore, period and hyphen, values of at most 500 characters. Never secrets or personal data. Never published to OCPI roaming partners. On create, sets the pairs; on PATCH, merges them into the stored ones: a key sent as "" or null is deleted, other keys keep their values.

Returns · 200

• idstringRequired
• tenant_idintegerRequired
• application_referencestringRequired
• processorstringRequired
• merchant_referencestringRequired
• payment_referencestringRequired
• created_bystringRequired
• created_atstringRequired
• settlement_ownerstring
  Default "external"
• metadataobject
  Your own key/value pairs (strings), such as a site host or a contract ID: at most 50 keys of 1-40 characters of A-Z, a-z, 0-9, underscore, period and hyphen, values of at most 500 characters. Never secrets or personal data. Never published to OCPI roaming partners. The session's bill's metadata (a session is its bill); writable with PATCH.
• station_metadataobject
  The station's metadata as it was when the bill was created, copied once and never changed afterwards, so historical attribution survives later edits. {} when it had none (or had no station).
• location_metadataobject
  The location's metadata as it was when the bill was created, copied once and never changed afterwards, so historical attribution survives later edits. {} when it had none (or had no location).
• statusenumRequired
  One of prepared, starting, charging, stopping, awaiting_bill, completed, canceled, reconciliation_required
• billBillRecordRequired
  Child attributes

  • warningsarray of object
    Set only on the response that creates the bill: tariff_differs_from_connector when the requested tariff is not the one that applies to the connector (details: requested_tariff_id, connector_tariff_id, connector_tariff_source).
  • idstringRequired
  • tenant_idintegerRequired
  • station_idintegerRequired
  • connector_idintegerRequired
  • sourcestringRequired
  • tariff_idintegerRequired
  • rate_minorstringRequired
  • hold_minorintegerRequired
  • currencystringRequired
    The bill's ISO 4217 currency, its tariff's (USD or CAD); every amount on the bill is in its minor units.
  • charging_tokenstringRequired
  • statusenumRequired
    One of open, final
  • energy_kwhstring | nullRequired
  • energy_whinteger | null
    Integer Wh of the finalized usage.
  • total_minorinteger | nullRequired
    Final bills: what the driver pays, in minor units, tax included when the bill has tax.
  • transaction_idinteger | nullRequired
  • created_atstringRequired
  • finalized_atstring | nullRequired
  • settlement_ownerenum
    One of managed, external · Default "managed"
  • billing_versionenum
    energy-v1: a simple tariff, total_minor = round_half_up(kWh × rate_minor). elements-v1: a complex tariff's elements and rules, frozen when the bill was created; rate_minor is its base rate.
    One of energy-v1, elements-v1 · Default "energy-v1"
  • cost_breakdownobject | null
    Final bills finalized from 2026-10-15: the itemised lines and adjustments behind total_minor, from the same calculation as tariff quotes.
    Child attributes

    • tariff_idinteger | null
      The stored tariff quoted; null for a simulation.
    • currencystringRequired
    • pricing_versionenumRequired
      energy-v1: a simple tariff (kWh × rate, unchanged); elements-v1: elements and rules.
      One of energy-v1, elements-v1
    • linesarray of QuoteLineRequired
      Child attributes

      • typeenumRequired
        One of ENERGY, TIME, PARKING_TIME, FLAT
      • elementintegerRequired
        Index of the element that priced this line.
      • reservationbooleanRequired
        The line prices a reservation.
      • quantitystringRequired
        Decimal quantity in unit (rounded to 6 places for display).
      • unitenumRequired
        One of kWh, h, session
      • price_minorstringRequired
        Minor units per unit (decimal string).
      • exact_minorstringRequired
        Unrounded amount, minor units (decimal string, 6 places).
      • amount_minorintegerRequired
        Amount rounded half up to integer minor units, for display. total_minor rounds the exact sum once, so line amounts may differ from it by rounding.
    • subtotal_minorintegerRequired
      The elements' exact sum rounded half up, before rules.
    • exact_subtotal_minorstringRequired
    • adjustmentsarray of QuoteAdjustmentRequired
      Child attributes

      • kindenumRequired
        One of group_discount, merchant_validation, max_session_cost
      • rulestringRequired
        The group discount id, the validation code, or max_session_cost_minor.
      • exact_minorstringRequired
      • amount_minorintegerRequired
        Negative: a reduction.
    • total_minorintegerRequired
      Integer minor units: the exact subtotal after rules, rounded half up once, plus the location's tax lines when they apply (tax). Bills finalize with this same calculation.
    • prepaidobject | nullRequired
      Child attributes

      • balance_minorintegerRequired
      • covered_minorintegerRequired
      • shortfall_minorintegerRequired
      • limit_reachedbooleanRequired
        The session's total reaches the balance: stop or top up.
    • tariff_alt_textarray of AltText
      The tariff's driver-facing descriptions, for receipts.
      Child attributes

      • languagestringRequired
        ISO 639-1 language code.
        Pattern ^[a-z]{2}$
      • textstringRequired
        Driver-facing description of the tariff.
        1–512 characters
    • idle_free_secondsinteger | null
      With idle_grace_minutes: the idle seconds that were free; absent otherwise.
    • activityobject | null
      Bills on complex tariffs only: the charging and idle time the bill was priced over. Null on quotes, simulations and simple tariffs (which price kWh only).
      Child attributes

      • methodenumRequired
        ocpp201_charging_state: the charger's OCPP 2.x chargingState. ocpp16_status: OCPP 1.6 connector statuses (Charging; SuspendedEV, SuspendedEVSE and Finishing are idle). ocpp16_status_and_power: those statuses, plus idle wherever the meter shows almost no power for a while. meter_power: the meter alone. none: not enough data; the whole transaction is charging time, as before idle detection (unless it drew less than 1 Wh: see reason no_energy).
        One of ocpp201_charging_state, ocpp16_status, ocpp16_status_and_power, meter_power, none
      • detectedbooleanRequired
        False: method none, and reason says why. A session with less than 1 Wh is all waiting (reason no_energy), and detected is true then, also with method none.
      • reasonstring | null
        Why nothing was detected (for example no_state_or_meter_data); no_energy: a session with less than 1 Wh is all waiting, billing neither TIME nor PARKING_TIME nor energy; else null.
      • charging_secondsintegerRequired
      • idle_secondsintegerRequired
      • waiting_secondsinteger
        Plugged in before the first charging: neither TIME nor PARKING_TIME.
        Default 0
      • intervalsarray of ActivityIntervalRequired
        The transaction from start to end, oldest first.
        Child attributes

        • startstringRequired
          UTC, ISO 8601.
        • endstringRequired
          UTC, ISO 8601.
        • stateenumRequired
          waiting: plugged in before the first charging, priced as neither TIME nor PARKING_TIME.
          One of charging, idle, waiting
    • taxobject | null
      With a location's tax lines (location_id on quotes, the station's location on bills): the tax lines, net and total. Absent without tax.
      Child attributes

      • price_modeenumRequired
        One of tax_exclusive, tax_inclusive
      • linesarray of QuoteTaxLineRequired
        Child attributes

        • namestringRequired
        • typeenumRequired
          One of percent, per_kwh
        • ratestringRequired
        • compoundbooleanRequired
        • excluded_componentsarray of enumRequired
        • registration_numberstring | nullRequired
          Printed on receipts.
        • base_minorstring | nullRequired
          percent lines: the exact amount taxed, minor units (decimal string, 6 places); null for per_kwh.
        • quantity_kwhstring | nullRequired
          per_kwh lines: the kWh taxed; null for percent.
        • exact_minorstringRequired
          Unrounded tax, minor units (decimal string, 6 places).
        • amount_minorintegerRequired
          The line's tax, rounded half up once.
      • net_minorintegerRequired
        The price before tax: total_minor minus tax_minor.
      • tax_minorintegerRequired
        The sum of the lines' amount_minor.
      • total_minorintegerRequired
        What the driver pays, tax included; the quote's and bill's total_minor.
  • limitobject | null
    The session limit set when the bill was started, with its stop and, once final, the overrun.
    Child attributes

    • typeenumRequired
      One of energy, amount
    • energy_kwhstringRequired
      The energy cap the platform enforces, in kWh; for an amount limit, the amount converted at rate_minor.
    • energy_whinteger | nullRequired
    • amount_minorinteger | nullRequired
      Amount limits: the limit in minor units.
    • currencystring | nullRequired
    • rate_minorstring | nullRequired
      Amount limits: the bill's per-kWh rate (minor units) the amount was converted at, with the per-kWh tax on bills whose prices exclude tax.
    • stop_reasonstring | nullRequired
      limit_reached once the platform decided to stop the session at its limit.
    • stop_requested_atstring | nullRequired
    • stop_energy_kwhstring | nullRequired
      Energy delivered (kWh) when the platform decided to stop.
    • stop_operationobject | nullRequired
      The latest stop the platform sent; succeeded means the charger route accepted it.
      Child attributes

      • idstringRequired
      • tenant_idintegerRequired
      • statusenumRequired
        One of dispatching, succeeded, rejected, unknown
      • resultobject | nullRequired
      • created_atstringRequired
      • updated_atstringRequired
    • final_energy_kwhstring | nullRequired
      Final bills: the billed energy in kWh.
    • final_amount_minorinteger | nullRequired
      Final bills: the billed total in minor units, including any fees.
    • overrun_kwhstring | nullRequired
      Final bills: final energy minus the energy cap, never below 0.
    • overrun_whinteger | nullRequired
    • overrun_minorinteger | nullRequired
      Final bills with an amount limit: final amount minus the limit, never below 0.
  • taxobject | null
    Bills at a location with tax lines: the configuration frozen when the bill was created. Absent without tax. usage.estimated_minor and total_minor include it; cost_breakdown.tax itemises it.
    Child attributes

    • location_idinteger | nullRequired
    • price_modeenumRequired
      tax_exclusive (the US norm): tariff prices exclude tax and the lines are added to them. tax_inclusive: tariff prices include every line, and the lines are taken out of the price the driver pays.
      One of tax_exclusive, tax_inclusive
    • linesarray of TaxLineRecordRequired
      The lines, in the order they apply, with the registration numbers receipts print.
      Child attributes

      • orderintegerRequired
        1 for the first line applied.
      • namestringRequired
      • typeenumRequired
        One of percent, per_kwh
      • ratestringRequired
        Decimal text: a percentage, or minor units per kWh.
      • compoundbooleanRequired
      • excluded_componentsarray of enumRequired
      • registration_numberstring | nullRequired
  • return_urlstring | null
    The return_url its payment was created with, where hosted checkout returns the driver; null otherwise.
  • metadataobject
    Your own key/value pairs (strings), such as a site host or a contract ID: at most 50 keys of 1-40 characters of A-Z, a-z, 0-9, underscore, period and hyphen, values of at most 500 characters. Never secrets or personal data. Never published to OCPI roaming partners.
  • station_metadataobject
    The station's metadata as it was when the bill was created, copied once and never changed afterwards, so historical attribution survives later edits. {} when it had none (or had no station).
  • location_metadataobject
    The location's metadata as it was when the bill was created, copied once and never changed afterwards, so historical attribution survives later edits. {} when it had none (or had no location).
  • usageobject | null
    Single bill reads only: live matched usage after start, a final snapshot once final.
    Child attributes

    • transaction_idinteger | nullRequired
      Transaction resource ID of the charging core.
    • activebooleanRequired
    • energy_kwhstring | nullRequired
      Decimal kWh string for display.
    • energy_whinteger | nullRequired
      Integer Wh for arithmetic.
    • estimated_minorinteger | nullRequired
      Integer minor units. On final bills this equals total_minor.
    • started_atstring | nullRequired
    • ended_atstring | nullRequired
    • power_winteger | null
      Latest reported charging power in watts; 0 once the transaction ended; null when the charger reports none.
    • soc_percentinteger | null
      Latest reported vehicle state of charge, when the charger reports it.
    • metered_atstring | null
      Timestamp of the meter sample behind power_w/soc_percent.
  • start_operationobject | null
    Single bill reads only: the journaled start dispatch, if any.
    Child attributes

    • idstringRequired
    • tenant_idintegerRequired
    • statusenumRequired
      One of dispatching, succeeded, rejected, unknown
    • resultobject | nullRequired
    • created_atstringRequired
    • updated_atstringRequired
  • progressenum | null
    Single bill reads only, managed bills: the driver-facing step. awaiting_payment: the hold is not authorized yet (checkout open, card declined or retrying). authorized: authorized, no start dispatched (the application starts it). starting: the start is being dispatched. waiting_for_vehicle: the start reached the charger; no transaction yet (plug in). charging: a matched transaction is active. ended: the transaction ended or the bill is final. start_failed: the start was rejected or its outcome is unknown. canceled: the payment was canceled or its checkout expired before any transaction. Null for externally settled bills and lists.
    One of awaiting_payment, authorized, starting, waiting_for_vehicle, charging, ended, start_failed, canceled
• usageobject | nullRequired
  Live matched usage while charging; a final snapshot once completed. Null before a transaction is observed and on canceled sessions.
  Child attributes

  • transaction_idinteger | nullRequired
    Transaction resource ID of the charging core.
  • activebooleanRequired
  • energy_kwhstring | nullRequired
    Decimal kWh string for display.
  • energy_whinteger | nullRequired
    Integer Wh for arithmetic.
  • estimated_minorinteger | nullRequired
    Integer minor units. On final bills this equals total_minor.
  • started_atstring | nullRequired
  • ended_atstring | nullRequired
  • power_winteger | null
    Latest reported charging power in watts; 0 once the transaction ended; null when the charger reports none.
  • soc_percentinteger | null
    Latest reported vehicle state of charge, when the charger reports it.
  • metered_atstring | null
    Timestamp of the meter sample behind power_w/soc_percent.
• start_operationobject | nullRequired
  Child attributes

  • idstringRequired
  • tenant_idintegerRequired
  • statusenumRequired
    One of dispatching, succeeded, rejected, unknown
  • resultobject | nullRequired
  • created_atstringRequired
  • updated_atstringRequired
• stop_operationobject | nullRequired
  Child attributes

  • idstringRequired
  • tenant_idintegerRequired
  • statusenumRequired
    One of dispatching, succeeded, rejected, unknown
  • resultobject | nullRequired
  • created_atstringRequired
  • updated_atstringRequired
• settlementSettlementSummaryRequired
  Child attributes

  • verificationstring
    Default "application_reported"
  • captured_minorintegerRequired
  • refunded_minorintegerRequired
  • net_minorintegerRequired
  • uncollected_minorinteger | nullRequired
  • statusenumRequired
    One of unreported, pending, unknown, failed, reported_unpaid, reported_partial, reported_paid, reported_refunded, reported_released

Errors