Change a bill's metadata

Path parameters

• tenant_idintegerRequired
• bill_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

• 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

Errors