Monta.comGuidesAPI ReferenceChangelog

Changelog

2024-01-18

:rocket: Feature

  • New endpoint for Prices Forecast /prices/forecast, this endpoint will enable partners to forecast prices for a given Charge Point and Price Group
  • Added field startSource on the Charges response, the full dictionary of types and descriptions can be found here
  • Added endpoints to create, update and delete Sponsored Charge Points, endpoints and request/response objects can be found here.
  • Added new Insights APIs - they are replacing the Charges Insights APIs:
    • /insights/charges/charger-report: Returns a list of charge points (owned by given teamId) with the number of charging sessions and the total Kwhs consumed.
    • /insights/charges/driver-report: Returns charge insights for the given teamId (and optionally teamMemberIds) broken down by team member.
      Takes only charges into consideration that were paid for by the provided teamId.
  • Added new Price Group Tags APIs - they allow you to assign tags to price group elements (charge pricings).
    • GET /price-group-tags - Retrieve your operators' tags
    • GET /price-group-tags/:id - Retrieve a tag by id
    • POST /price-group-tags - Create a new tag
    • PATCH /price-group-tags/:id - Update an existing tag
    • DELETE /price-group-tags/:id - Delete a tag
      Note: tags are scoped at operator level, so they can be used across an operator.
  • Price Group Tags are exposed on Charge Breakdowns
  • Price Group Tags can be assigned when creating Price Groups
  • Charge Points - added new fields:
    • chargePointModelId
    • isActive
  • Sponsored Charge Points - added new fields to chargePoint object:
    • chargePointModelId
    • brandName
    • modelName
    • firmwareVersion
    • maxKw
    • isActive
  • Charges contain a new object publicChargePoint. This gives you public information about the charge point, such as EVSE ID, address, brand, and model.
  • You can include deleted entries for Sponsored Charge Points in GET /api/v1/sponsored-charge-points
  • Added field completedAt and chargePointOperatorName for Charges
  • Added reservable and reservationTime for Charge Points
  • Added vatNumber to Teams model

:memo: Docs

  • We have added a new field x-sunset which specifies the date for removal on all deprecated fields / endpoints. Any field or endpoint that was announced to be removed already or soon was updated for removal by 01.04.2024 to give you more time to validate your integrations.

:bug: Fix

  • Generic Payment Sessions no longer require cardLast4 to be present to be persisted. For now, we persist in any Generic Payment Session that has any field filled in. Very soon will make it a requirement to provide at least one provider and externalId
  • Generic Payment Sessions require the fields provider and externalId to be provided.
  • Fixed a couple of fields that were not mapped correctly on the Tariffs response
  • The vat flag was not applied correctly to spot fees.
  • Deleted Team Members are retrievable via GET /api/v1/team-members/{id}
  • When using the Driver Report, Team Members that did not yet create an account on Monta are excluded, avoiding a potential 500 error.
  • Sponsored Charge Points: deletedAt field is properly populated
  • Installer Jobs: filtering by siteId is possible now

🚧

Deprecation Note

  • We have deprecated Charges Insights APIs (/charges/insights). They will be removed by 01.04.24. Moving forward make use of the new Insights APIs.

🚧

Beta

The /prices/forecastis currently in BETA phase, changes and might be subject to change in a near future release

2023-11-23

:rocket: Feature

  • New endpoint for Charges insights /charges/insights
    • This endpoint lets you get insights and breakdowns about charges for a specified period. You can get these insights:
      • totalKwh
      • totalPrice
      • totalCost
      • totalSessions
    • Broken down by charges performed at:
      • operator
      • external
      • sponsored
      • total
  • New endpoint to get and list Currencies
  • New endpoint to get and list Operators
  • Added support to set the flag canManageTeamMembers for Team Members via POST and PATCH.
  • Updated documentation around Charges state
  • Added new the ChargePointAuthToken partnerExternalId on the Charges response.
  • Team Members: Added new filter to filter Team Members by their state.
  • Team Members: Added new filters to filter Team Members by their userI, phone or email.
  • Team Members: Added new endpoint to resend Team Member invitations.

:bug: Fix

  • The Resource Not FoundThe message was ambiguous in specific situations; this has been fixed now
  • Add new price group type reimbursement
  • Renamed partnerId in charge.genericPaymentSession to partnerExternalId
  • Fix an issue with sponsoredChargePointId missing on some sponsored charges
  • Fix an issue where empty tariffs were added to each charge breakdown item
  • Renamed occp to ocpp, the protocol name was wrongly spelled.
  • Fix Charge Points costPriceGroup was wrongly mapped and therefore always null
  • Fix Charge Auth Tokens partnerExternalId and partnerCustomPayload were not being persisted during the creation step

🚧

Deprecation Note

  • We have deprecated priceBreakdown and costBreakdown fields on the Charge model both fields will be removed by 31.01.24. As a replacement for those fields, please use charges/:chargeId/breakdown.

2023-09-29

:rocket: Feature

  • When creating a Subscription you can set discountPercentage and discountAbsolute
  • New endpoint for Charges at /charges/:id/breakdown to retrieve price and cost breakdown
  • New endpoints to manage Installer Jobs - they can be created, deleted, and retrieved
  • New Webhook entity added: Team Members - you can use this to get informed when a team member accepts their invite.
  • You can use the Webhook Config endpoint to limit webhooks to certain Event Types, currently:
    • charges
    • charge-points
    • sites
    • team-members
    • or provide * to get all entity changes delivered to your webhook endpoint
  • Added two new fields to Wallet Transactions:
    • kind: gives a hint about the reason for this transaction, ie. charge-sponsored, tax-refund, ...; Note that as of now we have 118 kinds and this list will grow over time. We will add more docs moving forward.
    • vatPercentage: the amount of VAT that was part of this transaction
  • Allow filtering Subscriptions by subscriptionPurchaseId. This allows you to find a subscription related to a wallet transaction with referenceType SUBSCRIPTION_PURCHASE and its referenceId
  • New endpoint to delete a Tariff Period Group
  • New endpoint to delete a Tariff Recurring Period
  • New endpoint to delete a Site
  • New endpoint to delete a Charge Point
  • Added currency as part of the Teams
  • Team Members have a new field `canRequestSponsoring which you can read/write
  • Webhooks are enabled for all existing and new consumers
  • Charges that you paid for can be obtained by using the new operatorRole filter on GET /charges with value payer
  • Added new fields to Charge Point model to determine its Price Groups
    • priceGroupId - id of the public price group
    • roamingPriceGroupId - id of the roaming price group
    • costPriceGroupId - id of the cost price group
    • sponsoredPriceGroupId - id of the sponsored price group
  • Added new endpoints to retrieve your Payment Terminals
  • Added new endpoints to retrieve your Subscription Purchases
  • Added new endpoints to retrieve and setup Charge Point Integrations
  • New Webhook entity added: Wallet Transaction - you can now get notified when a wallet transaction is created or updated.
  • New Webhook entity added: Subscription - you can use this to get informed when this entity is created or updated.
  • New Webhook entity added: Plan - you can use this to get informed when this entity is created or updated.
  • New Webhook entity added: Installer Job - you can use this to get informed when this entity is created or updated.
  • New Webhook entity added: Price Group - you can use this to get informed when this entity is created or updated.
  • New Webhook entity added: Team - you can use this to get informed when this entity is created or updated.
  • New Webhook entity added: Team - you can use this to get informed when this entity is created or updated.
  • Add new metadata section for Wallet Transactions metadata section will used to enrich transactions with either Charge or Tax Refund data.
  • Added granular scopes: you can now specify not only the entities accessible by a consumer but also if they can read, write, or delete (read more)
  • From now onwards, it is possible to patch the Team owner via Api
  • Exposing the chargePointKw for the Charges response.
  • chargePointIds are not mandatory anymore for patching a Team Members
  • Exposing the serialNumber for Sponsored Charge Points responses.

:bug: Fix

  • Fixed connectorId is not mandatory to create Charge Point Integrations anymore.
  • Add a new flag called autoConnectto allow setting up Charge Point Integrations without having to point the Charge Point to Monta
  • Fixed issue when setting up Charge Point Integrations the connectorId was being set to 0 instead of 1 when not provided.
  • Sorting Charge Points and Sites by location now allows negative latitude and longitude.

2023-09-19

:rocket: Feature

  • When creating a Subscription of type tax-refund you can modify payoutPerKwh and priceIncludesVAT field.

:bug: Fix

  • Update Plans and Subscription models
  • Fixed fromDate/toDate filter for Wallet Transactions
  • Add endDayOfWeek to Tariff Recurring Period

2023-09-14

🚧

Deprecation Note

  • We have deprecated operatorId field on Team models. Use the new field operator instead. The old field will be removed by 01.12.23.
  • We have deprecated maxKW field on various model. Use the new field maxKw instead. The old field will be removed by 01.12.23.

:rocket: Feature

  • Introduced endpoints for listing and retrieving Sponsored Charge Points
  • Added endpoints for listing and retrieving Plans
  • Implemented endpoints for creating, updating, canceling, and fetching Subscriptions
  • Added support for specifying multiple days for Tariffs Recurring Periods
  • Charge Auth Tokens Added support for the following fields when creating or updating:
    • userId
    • teamId
    • montaNetwork
    • roamingNetwork
    • activelUntil
  • Price Groups
    • New endpoint to set a default price group
    • New endpoint to apply a price group to Team Members, Charge Points, and Sites
    • Added the ability to specify a from/to dates for a fee
    • Price groups now support multiple tariffs
  • Webhooks
    • Expanded webhook support for Charge Points and Sites
    • Charges events will also be triggered when the charge was paid by the operator

:bug: Bugs

  • Fixed display name missing for team members on the charges endpoint

:memo: Docs

  • Updated and added API documentation for Price Groups, Subscriptions, Sponsored Charge Points, and more

2023-08-31

:rocket: Feature

  • Create a Team no longer requires userId to be provided
  • Create/Update Tariffs no longer requires countryAreaId to be provided
  • Added the user and team member (if from CP's team) associated with a Charge
  • Charge Auth Tokens usage can now be limited to the operator's network.
  • Added support for partnerExternalId and partnerCustomPayload for Wallet Transactions
  • Added patch endpoint for Wallet Transactions
  • Added new filters to GET /wallet-transactions, you can now filter by:
    • referenceType
    • referenceId
    • state
    • group
    • partnerExternalId
  • Added new field activeAt to Charge Point model, indicating when the Charge Point was (last) activated

:bug: Fix

  • Price Groups: Added type roaming
  • Tariffs:
    • Fixed an issue where GET resource by ID would return 401
    • Fixed an issue with the validation of non-overlapping recurring periods with the same weekday
    • Fixed an issue with PATCH /tariffs/:idThat would lead to BAD_REQUEST

:memo: Docs

  • Added/Updates API documentation for Wallet Transactions, Price Groups, Subscriptions, and others.

2023-08-16

:rocket: Feature

  • Beta / For selected partners: We are launching our webhooks system, starting with charge transactions. Check out the guide and the api docs. 🚀
  • Added support to starting a Charge with kWhLimit or socLimit
  • Added new endpoints to list and fetch Country Area
  • Added displayName and priceGroupId for the Team Member model.
  • Expanded patch Team Member to support more fields
  • Added new filter by the state for Charge Points
  • Operators can now access the Charges paid by their teams via GET /charges/:id endpoint. However, they are not yet included in the GET /charges endpoint. This will come in a later release.
  • Added new field type for Charges

:bug: Fix

  • Fixed access checks when fetching Wallet Transactions by id were causing 403
  • Fixed access checks when fetching Price Groups by id were causing 403

:memo: Docs

  • Added/Updates API documentation for Team Members, Price Groups, and others.
  • Split our API docs in guides and api reference

2023-08-03

:rocket: Feature

  • Added new endpoints to list, create, update, and delete Price Groups
  • Added endpoint to create (invite) and delete a Team Member
  • Added endpoint to delete a Team
  • Allow listing deleted Sites and Charge Points
  • Partners can now use Monta's receipt system when providing genericPaymentSession when starting a Charge
  • New Endpoints to fetch, list, create and update the following entities in the tariffs context:
    • Tariffs
    • Period Groups
    • Recurring Periods
  • Added endpoint to generate the Prices for a given tariff

:warning: Breaking change

  • Previously, the userId field for Team Member was a non-nullable field, from this version onwards this field is nullable.

:memo: Docs

  • Added/Updates API documentation for Price Groups, Team Members, and Tariffs
  • Added detailed documentation for Price Groups.

2023-07-20

:rocket: Feature

  • Beta Price Groups endpoints are officially retired. The new price groups endpoints will be available soon
  • Wallet Transactions can now be fetched by teamId
  • Added the referenceId field for Wallet Transactions
  • Added support for filtering resources with null partnerExternalId
  • Added new /api/v1/consumers/me, api/v1/auth/me is now deprecated, please migrate to the new one
  • Exposing operator data for:
    - Teams
    - Charges
    - Charge Points,
    - Charge Auth Tokens,
    - Sites

:bug: Fix

  • Fixed typo for team-has-fund payments method

:memo: Docs

  • Removed beta Price Groups docs
  • Added documentation for new Consumer endpoint
  • Updated documentation for existing endpoints, query parameters, and fields

2023-07-06

:rocket: Feature

  • Added a Patch Team Member endpoint. Setting charge point ids for a Team Member is now supported
  • Ability to sort Charge Points by location via the sortByLocation query parameter
  • Updated Charge Point Model to expose the models supported features
  • Updated Charge Point model to expose the evse_id

:memo: Docs

  • Updated documentation for new endpoints, query parameters, and fields

2023-06-20

:rocket: Feature

  • Ability to filter Charges by partnerExternalId
  • Ability to provide partnerExternalId and partnerCustomPayload when starting a Charge
  • Expose new fields partnerExternalId and partnerCustomPayload for Charges
  • New patch endpoint to update partnerExternalId and partnerCustomPayload for Charges
  • New Endpoints to create and update the following entities:
    • Teams
    • Sites
    • Charge Points
  • New Endpoints to fetch one or multiple:
    • Charge Point Connectors
    • Charge Point Brands
    • Charge Point Models
    • Countries

:memo: Docs

  • Fixed missing charge-points/maps query filters
  • Added documentation with new endpoints:
    • Teams
    • Sites
    • Charge Points
    • Charge Point Connectors
    • Charge Point Brands
    • Charge Point Models
    • Countries

2023-05-02

:rocket: Feature

  • Added new Charge Point fields: brandName, modelName, firmwareVersion and integrationType
  • Added new field partnerCustomPayload on the following entities:
    • Charge Point,
    • Charge Auth Token,
    • Charge Point,
    • Team
  • New patch endpoint to update partnerExternalId and partnerCustomPayload for the following entities:
    • Charge Point,
    • Charge Auth Token,
    • Charge Point,
    • Team
  • Added endpoints to fetch and list Team members.
  • Ability to create Charge Auth Token assigned to a User.

:bug: Fix

  • Removed legacy \chargeAuthTokens endpoint.

:memo: Docs

  • Updated Charge Point states.

2023-03-20

🚀 Feature

  • Added new fields to Charge model: soc (State of Charge), socLimit and priceLimit
  • Added new field to Charge Point model: cablePluggedIn - indicates if a cable is plugged in currently
  • Added partnerExternalId to Charge Point, Site, Charge Auth Token and Team models
  • Added query parameter partnerExternalId to filter by it on Charge Point, Site, Charge Auth Token and Team index endpoints

🚧

Beta

  • Added endpoints to fetch Price Groups - this group of endpoints is subject to change in a near future release

2023-03-01

🐛 Fix

  • ⚠️ Breaking change: Wallet transaction's field updated_at is optional

2023-02-01

❗️

New Base URL

The new base url for the Partner API is partner-api.monta.com

The previous one (partner-api.monta.app) is deprecated and will continue to work until 01.04.2023.

🚀 Feature

  • Added support to create and delete Charge Auth Tokens
  • Added support to fetch one or multiple Teams
  • Added field operatorNote to Charge Point responses

🐛 Fix

  • Renamed /chargeAuthTokens endpoint to /charge-auth-tokens
    request parameters and response payloads will remain the same,
    we will support both endpoints until at least 13-02-2023
    then we will effectively remove /chargeAuthTokens

📝 Docs

  • Updated API documentation includes:
    • New endpoints to create and delete Charge Auth Tokens
    • New endpoints to fetch Teams
    • New Charge Point field
    • Instructions to migrate from the deprecated /chargeAuthTokens endpoint

2023-01-04

🚀 Feature

  • Charges can now be filtered by the combined filter chargeAuthType and chargeAuthId
  • New endpoints added to fetch one or multiple Charge Auth Token
  • Added a new field lastMeterReadingKwh to Charge Point

📝 Docs

  • Updated API documentation includes:
    • New endpoints to fetch Charge Auth Token
    • New Charge filters
    • New Charge Point field

🐛 Fix

  • Endpoint /api/v1/me would not work with certain scopes
  • Fetching a Wallet Transaction by id was not working

2022-12-14

🚀 Feature

  • Filter Charges, Sites and Charge Points by teamId
  • Wallet Transactions now have the createdAt and updatedAt fields
  • New fields kwhPerHourand stopReason added to Charge, allowing you to retrieve information:
    • The total Kwh consumed for that charge, split by hour
    • The reason why the charge was stopped

📝 Docs

  • Endpoints now also have the most important errors documented
  • General cleanup of examples and descriptions to help auto-generate valid requests

2022-11-07

🚀 Feature

  • New field chargeAuth added to Charge, allowing you to retrieve information about the authentication method used to authenticate the charge
  • Charge, ChargePoint and Site now have the createdAt and updatedAt fields

🐛 Fix

  • siteId query param of /api/v1/charge-points would allow for string values. This will now return a 400 - Bad Request if the value is not a number.

📝 Docs

  • Update documentation for auth/me and pagination parameters.

2022-09-16

🚀 Feature

  • Charge transactions can be filtered by fromDate and state
  • Charge transactions are sorted by createdAt descending

⚠️ Breaking change

  • Previously, the pagination page parameter would handle 0 and 1 equally but return an incorrect pagination meta data. Our Pagination page parameter was updated to start from 0. A page of 1 will now return the second page.

2022-09-14

🚀 Feature

  • New endpoint added for reserving a Charge Point.

⚠️ Breaking change

  • fromType and from on wallet transaction model is nullable now (e.g. for deposit transactions)
  • toType and to on wallet transaction model is nullable now (e.g. for withdrawal transactions)

2022-07-06

🚀 Feature

  • New map endpoint for Charge Points, allowing you to retrieve Clusters, Sites and Charge Points to be rendered on a map.
  • Added field deeplinks to Charge Points. They allow you to start charging via Monta app or web app [no registration needed].
  • Added auth scopes to credentials. Scope determines if you are eligible to access certain endpoints.

📝 Docs

  • Update contact url in docs.

2022-06-13

🚀 Feature

  • Rate-limit will be enforced from now on

⚠️ Breaking change

  • staticMapUrl removed from Location model

2022-06-03

🧹 Chore

  • Better error handling

2022-06-01

⚠️ Breaking change

  • Rename Connector.slug to Connector.identifier
  • Rename query param from/to to fromDate/toDate in wallet transactions

🐛 Fix

  • Throw 401 instead of 404 when client credentials are wrong

📝 Docs

  • Improve description for pagination parameters
  • Add schema for TeamOrOperator
  • Add enum values to all enum types
  • Add security schemes

2022-05-31

🚀 Feature

  • Initial Release with Sites, Charge Points, Charges, Wallet Transactions and Start/Stop charging