--- title: "Retrieve a list of charges" method: GET path: "/api/v1/charges" tags: ["Charges"] --- # Retrieve a list of charges `GET /api/v1/charges` Required scope: `charge-transactions:read`
Organization authorization: `supported`

**Pagination Limit:** A maximum of 20,000 charges can be retrieved. To retrieve more data, use more specific filters, like date range filters such as `fromDate`, `toDate`, `fromUpdatedDate`, `fromCompletedDate`, or `toCompletedDate`. ## Query parameters - `page` integer - `perPage` integer - `teamId` integer, nullable — Filter to retrieve charges with specified `teamId`
*Note:* Depending on the `operatorRole` the `teamId` will filter differently:
operatorRole = owner: will filter charges from charge points that are owned by the team
operatorRole = payer: will filter charges paid by team - `operatorId` integer, nullable — Filter to retrieve charges with specified `operatorId`
*Note:*The `operatorId` must be in the consumer’s operatorIds or, if empty, belong to the organization’s sub-operators.
*Note:* When not provided and `operatorRole = payer` the default operator will be used for the given consumer, if the default operator cannot be assigned the request will be rejected - `chargePointId` integer, nullable — Filter to retrieve charges with specified `chargePointId` - `siteId` integer, nullable — Filter to retrieve charges with specified `siteId` - `state` 'reserved' | 'starting' | 'charging' | 'stopping' | 'paused' | 'suspended_ev' | 'suspended_evse' | 'scheduled' | 'stopped' | 'completed', nullable — Filter to retrieve charges by `state` - `fromDate` string, date-time, nullable — Filter to retrieve charges where `createdAt` >= `fromDate` (ISO8601: yyyy-MM-ddTHH:mm:ssZ) - `toDate` string, date-time, nullable — Filter to retrieve charges where `createdAt` <= `toDate` (ISO8601: yyyy-MM-ddTHH:mm:ssZ) - `fromUpdatedDate` string, date-time, nullable — Filter to retrieve charges where `updatedAt` >= `fromUpdatedDate` (ISO8601: yyyy-MM-ddTHH:mm:ssZ) - `fromCompletedDate` string, date-time, nullable — Filter to retrieve charges where `completedAt` >= `fromCompletedDate` (ISO8601: yyyy-MM-ddTHH:mm:ssZ) - `toCompletedDate` string, date-time, nullable — Filter to retrieve charges where `completedAt` <= `toCompletedDate` (ISO8601: yyyy-MM-ddTHH:mm:ssZ) - `chargeAuthType` 'rfid' | 'vehicleId' - `chargeAuthId` string, nullable — Filter to retrieve charges by the charge authentication id, must be combined with `chargeAuthType`
*Note*: for type vehicleId `chargeAuthId` must not include the VID: prefix - `partnerExternalId` string, nullable — Filter charges by `partnerExternalId`, to filter only resources without `partnerExternalId` *use* `partnerExternalId=""` - `operatorRole` 'owner' | 'payer' — Enumerate the possible filters for operator role ## Response `200` List of charges that match the criteria - OffsetBasedResponse6 - `data` Charge[], required - `id` number — Id of the charge - `humanReadableId` string, required — The human readable id for this charge - `user` PublicUser, required - `id` integer, required — Id of the user - `displayName` string, required — Formatted name to be displayed - `isGuest` boolean, nullable — Indicates whether this user is a guest (ad-hoc) user who has not yet completed registration - `teamMember` SimpleTeamMemberDto - `id` integer, required — Id of the team member - `teamId` integer — Team id of team member - `displayName` string, nullable — The team member display name, formats can be: `First and Last Name`, `User: #id`, `email`, or `phone` - `partnerExternalId` string, nullable — External Id of this entity, managed by you. - `userId` integer, nullable — User id of team member. If the user does not exist yet, it will be null. - `type` 'external' | 'operator' | 'sponsored', required - `chargePointId` integer — Id of the charge point related to this charge - `publicChargePoint` PublicChargePoint, required - `id` integer — Id of this charge point - `evseId` string, required — The EVSE id for this charge point - `name` string, nullable — Name of the charge point - `chargePointOperatorId` integer — The charge point operator id - `chargePointOperatorName` string, required — The charge point operator name - `location` Location, required - `coordinates` Coordinates - `latitude` number, double — Latitude value of coordinate - `longitude` number, double — Longitude value of coordinate - `addressLabel` string, nullable — The full address. - `address` PartialAddress - `address1` string, nullable — First line of address - `address2` string, nullable — Second line of address - `address3` string, nullable — Third line of address - `zip` string, nullable — Zip-code - `city` string, nullable — City (readable) - `province` string, nullable — Province - `country` string, nullable — Country (readable) - `countryAreaId` integer, nullable — Country area id - `maxKw` number, double, nullable — Max KW available at this charge point. - `chargePointModelId` integer, nullable — The ID of the charge point model for this charge point. - `brandName` string, nullable — Brand name for this charge point - `modelName` string, nullable — Model name for this charge point - `deletedAt` string, date-time, nullable — Date this charge point was deleted - `sponsoredChargePointId` integer, nullable — Id of the sponsored charge point related to this charge - `priceGroupId` integer — Id of the price group related to this charge. Note: The underlying price/costGroup models can change and you have to use other fields to get the historic data (costBreakdown, priceBreakdown, price) - `costPriceGroupId` integer, nullable — Id of the cost price group related to this charge - `memberCostPriceGroupId` integer, nullable — Id of the member cost price group related to this charge - `siteId` integer, nullable — Id of the site in which the charge point that performed this charge is - `promotionCodeId` integer, nullable — Id of the promotion code related to this charge - `createdAt` string, date-time, required — Creation date - `updatedAt` string, date-time, required — Update date - `cablePluggedInAt` string, date-time, nullable — Date when cable was plugged in - `startedAt` string, date-time, nullable — Date when charge started - `stoppedAt` string, date-time, nullable — Date when charge stopped - `fullyChargedAt` string, date-time, nullable — Date when EV was fully charged - `releasedAt` string, date-time, nullable — Date indicating when the cable was released.
**Note:** This value is meaningful only if the charge point properly supports Release Detection. - `failedAt` string, date-time, nullable — Date when charge failed - `timeoutAt` string, date-time, nullable — Date when charge timed out - `completedAt` string, date-time, nullable — Date when charge was considered completed - `state` 'paying' | 'reserved' | 'starting' | 'charging' | 'stopping' | 'paused' | 'scheduled' | 'stopped' | 'releasing' | 'released' | 'completed' | 'other', required — Enumerate the various types of charge state - `rawState` string, required — The original charge state value from the charge point before any mapping. While state provides normalized values for consistency, rawState preserves the exact state reported by the charge point. Use this when you need fine-grained state information or want to distinguish between similar states. This field may contain values not present in the 'state' enum as new charge point states are introduced. - `startSource` string, nullable — Indicates the starting source for this charge, e.g app-ios, app-android
**Note:** This is an ever-growing list, new values might be added. Please make sure to implement appropriate fallbacks - `consumedKwh` number, double, nullable — Consumed Kwh - `kwhLimit` number, double, nullable — Configured Kwh limit for this charge - `kwhPerHour` KwhPerTime[], required — List of consumed kWh split by hour (1 hour buckets) - `time` string, date-time, required — Start time for the sum of the kWh - `value` number, double — Sum of kWh - `kwhPerMaxResolution` KwhPerTime[], required — List of consumed kWh split by maximum available resolution (ie. 15min buckets) - `time` string, date-time, required — Start time for the sum of the kWh - `value` number, double — Sum of kWh - `costBreakdown` ChargeCost[], required — Detailed breakdown of the costs by hour
**Note:** Deprecated, this field will be be removed by *01.04.2024*, Use the `charges/:chargeId/breakdown` endpoint instead - `time` string, date-time, required — Hour for the sum of the cost - `value` number, double — Sum of cost for this hour - `priceBreakdown` ChargePrice[], required — Detailed breakdown of the prices by hour
**Note:** Deprecated, this field will be be removed by *01.04.2024*, Use the `charges/:chargeId/breakdown` endpoint instead - `time` string, date-time, required — Hour for the sum of the price - `value` number, double — Sum of price for this hour - `startMeterKwh` number, double, nullable — Kwh of the meter before charging started - `endMeterKwh` number, double, nullable — Kwh of the meter after charging stopped - `price` number, double, nullable — Price for this charge - `priceLimit` number, double, nullable — Configured price limit for this charge - `cost` number, double, nullable — Cost incurred for this charge - `averagePricePerKwh` number, double, nullable — Average price per Kwh - `averageCo2PerKwh` number, double, nullable — Average CO2 consumption per Kwh - `averageRenewablePerKwh` number, double, nullable — Average percentage of renewable energy per Kwh - `failureReason` string, nullable — Failure reason for this charge - `stopReason` string, nullable — Reason why this charge stopped - `paymentMethod` 'free' | 'team-has-fund' | 'team-has-auto-refill' | 'source' | 'payment', nullable — Payment method for this charge - `note` string, nullable — A note taken for this charge - `currency` Currency1 - `identifier` string, required — Currency identifier, e.g. dkk - `name` string, required — Readable name of currency - `decimals` integer — Number of decimals for this currency - `payingTeam` PayingTeam - `id` integer — Id of the paying team - `publicName` string, required — Public name of the team - `operatorId` integer — Id of the operator the paying team belongs to - `sponsorTeam` SponsorTeam - `id` integer — ID of the sponsor team - `publicName` string, required — Public team name - `operator` Operator - `id` integer — ID of the operator - `name` string, required — Name of operator - `identifier` string, required — Identifier of operator - `partnerId` integer, nullable — Id of the partner - `vatNumber` string, nullable — VAT number - `chargeAuth` ChargeAuthentication - `type` 'vehicleId' | 'rfid' | 'app', required — The method type used to authenticate a charge - `id` string, required — The id of the chosen authentication method - `partnerExternalId` string, nullable — External Id of this entity, managed by you. - `soc` StateOfCharge - `percentage` number, double — Value of SoC in % - `source` 'charge-point' | 'vehicle', required — Source of this value, eg vehicle or charge-point - `socStart` number, double, nullable — State of charge at the start of the session, if available - `socLimit` number, double, nullable — Configured SoC limit for this charge - `genericPaymentSession` GenericPaymentSession - `provider` string, required — The provider of the payment session - `externalId` string, required — The external id of the payment session. Allows retrieving receipts via receipt.monta.com by using date and `externalId` or `cardLast4`. - `partnerExternalId` string, nullable — External Id of this entity, managed by you. - `cardBrand` string, nullable — The brand of the card used for the payment session - `cardLast4` string, nullable — The last 4 digits of the card used for the payment session. Allows retrieving receipts via receipt.monta.com by using date and `externalId` or `cardLast4`. - `amount` number, nullable — The amount of the payment session. Negative amounts will be rejected by the API - `partnerExternalId` string, nullable — External Id of this entity, managed by you. **We recommend to fill this always with a unique identifier from your side,since it allows you to find a started charge later, even if this requests'response was not captured by you or something went wrong.** - `smartChargeId` integer, nullable — The smart charge id for this charge, if applicable. **Note:** If not null, this indicates the charge was a smart charge. - `partnerCustomPayload` object[], nullable — Custom JSON payload for this entity, managed by you. - `chargePointKw` number, double, nullable — The charge point KW recorded during the charge. - `signedData` SignedData - `format` 'OCMF' | 'PCDF' | 'ISA_EDL_40_P' | 'ALFEN' | 'EDL_40_P' | 'EDL_40_SIG' | 'EDL_40_MENNEKES' | 'UNKNOWN', required — Enumerate the possible charge signed data formats - `certificate` string, nullable — Public key for the signature. - `startMeter` string, nullable — Originating from the charge point for the start recording. The format is the exact format received from the charge point
*Note:* some formats sends both start and end data in the signed `endMeter` data. In this case this is null. - `endMeter` string, required — Originating from the charge point for the end recording. The format is the exact format received from the charge point. - `emaidProviderId` string, required — The first 5 characters of an EMAID, which is the provider id. - `vehicleId` integer, nullable — The vehicle id for this charge, vehicle details can be fetched from the vehicle API - `vid` string, nullable — The VID recorded for this charge, if reported by the charge point. - `protocolData` ChargeProtocolData, required - `oicp` OicpChargeProtocolData - `sessionId` string, nullable — The unique identifier of the session - `ocpi` OcpiChargeProtocolData - `cdrId` string, nullable — The unique identifier assigned to the charge data record (CDR) - `meta` MontaPageMeta, required - `itemCount` integer, required - `currentPage` integer, required - `perPage` integer, required - `totalPageCount` integer, required - `totalItemCount` integer, required ## Other responses - `400` — The request is invalid - `401` — Consumer with provided credentials was not found - `403` — Operator doesn't have access to resource - `404` — Entity with the provided id was not found --- [API](https://skmtc.net/monta/apis/monta-partner-api.md) · [All operations](https://skmtc.net/monta/apis/monta-partner-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/monta/monta-partner-api/versions/517e18f11015/schema)