API docs by Redocly

API doc for NovoWatt app - Admin API (1.0.0)

Download OpenAPI specification:

This is the API documentation for Novowatt app.

Authentication

Authenticate a user and return a token

Authenticate a user and return a token

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
email
required
string <email>

Email address of the user

password
required
string

Password of the user

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "ok": true,
  • "token": "678f81f18e80dea828493b88",
  • "user": {
    }
}

Subscriptions

Get subscriptions

Returns subscriptions with location_id preserved and mapped location data for support visibility.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
subscription_plan_id
string
merchant_id
string
status
string
user_name
string
user_email
string
user_phone
string
user_id
string

Filter subscriptions by user (use to fetch a single user's subscriptions, e.g. for a subscription detail view).

page
integer
per_page
integer

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ],
  • "total": 1,
  • "page": 1
}

Get locations enabled for subscription plan

Returns locations whose EVSEs enable the requested subscription plan. Admin callers must provide at least one plan ID; this endpoint does not fall back to all plans.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
subscription_plan_id
string

Single subscription plan ID.

subscription_plan_ids
string

Comma-separated subscription plan IDs.

name
string

Case-insensitive location name search.

page
integer
Default: 1
per_page
integer
Default: 10

Number of locations per page. Defaults to 10 for admin list display.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ],
  • "total": 1,
  • "page": 1,
  • "per_page": 10
}

Update subscription support details

Admin/CS endpoint for changing support-managed subscription details after purchase. Only admin roles Superadmin and CS may call this PUT endpoint. Supported fields are location_id, user_email, and user_phone; Admin API forwards only those supported fields. When location_id is provided, the Subscription service validates the subscription, target location, plan enablement, and same-location active/effective conflict before updating.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
subscription_id
required
string

Subscription ID to update.

Request Body schema: application/json
required
non-empty
location_id
string

Target location ID. The location must enable the subscription's plan.

user_email
string <email>

Subscription email to store on the subscription record.

user_phone
string

Subscription phone to store on the subscription record.

Responses

Request samples

Content type
application/json
{
  • "location_id": "66337ada513dff7cb0219963",
  • "user_email": "[email protected]",
  • "user_phone": "+6591234567"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Deprecated legacy user active subscription mapping

Deprecated. Active subscriptions are now resolved from the subscriptions collection and this endpoint no longer rebuilds legacy singular user active subscription fields.

Authorizations:
(AuthorizationTokenAuthorizationRole)

Responses

Response samples

Content type
application/json
{
  • "ok": false,
  • "msg": "This legacy user active subscription mapping endpoint is deprecated."
}

Activate a subscription

Activates the given subscription via the subscription service and records an admin log entry.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
subscription_id
required
string

Mongo ObjectId of the subscription

Responses

Request samples

Content type
application/json
{
  • "subscription_id": "string"
}

Response samples

Content type
application/json
{
  • "ok": true
}

Deactivate a subscription

Deactivates the given subscription via the subscription service and records an admin log entry.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
subscription_id
required
string

Mongo ObjectId of the subscription

Responses

Request samples

Content type
application/json
{
  • "subscription_id": "string"
}

Response samples

Content type
application/json
{
  • "ok": true
}

Export subscriptions to Excel

Exports the filtered subscription list as an .xlsx file. Accepts the same filters as the list endpoint.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
subscription_plan_id
string
merchant_id
string
status
string
Enum: "active" "waiting_for_active" "expired" "cancelled"
active_from
string <date>
active_to
string <date>
page
integer >= 1
per_page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": false,
  • "msg": "Something went wrong, please contact CS for supporting."
}

Pay for a subscription

Triggers payment for an existing subscription via the subscription service. An optional promo code may be applied. Emits an admin activity log on success.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
subscription_id
required
string

Mongo ObjectId of the subscription

promo_code_id
string

Responses

Request samples

Content type
application/json
{
  • "subscription_id": "string",
  • "promo_code_id": "string"
}

Response samples

Content type
application/json
{
  • "ok": true
}

Backfill user fields on subscriptions

Maintenance job that iterates subscriptions missing denormalized user fields (user_name, user_email, user_phone) and populates them from the users collection.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
limit
integer
Default: 1000

Batch size per iteration.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "Processed all subscriptions successfully"
}

Delete a subscription

Deletes the given subscription via the subscription service and records an admin log entry capturing the previous state.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
subscription_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Mark subscription payment as paid

Marks the subscription's payment as paid and activates it. Records an admin log entry on success.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
subscription_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Get subscription statistics

Returns usage/statistics for a single subscription from the subscription service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
subscription_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

List transactions for a subscription

Returns transactions associated with a single subscription from the subscription service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
subscription_id
required
string
query Parameters
page
integer >= 1
per_page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Users

Deprecated legacy active subscription plan rebuild

Deprecated. Active subscription plan data is no longer rebuilt onto user records because active subscriptions are resolved from the subscriptions collection.

Authorizations:
(AuthorizationTokenAuthorizationRole)

Responses

Response samples

Content type
application/json
{
  • "ok": false,
  • "msg": "This legacy active subscription plan rebuild endpoint is deprecated."
}

Companies

Get all companies

Get all companies

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
keyword
string

Get companies by name, address,....

page
integer

Page number

per_page
integer

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "total": 25,
  • "page": 1,
  • "data": [
    ]
}

Create a new company

Create a new company

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
name
required
string

Name of the company

address
required
string

Address of the company

city
required
string

City of the company

country
required
string

Country of the company

phone
required
string

Phone number of the company

email
required
string

Email of the company

website
required
string

Website of the company

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Get a company by ID

Get a company by ID

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
companyId
required
integer

ID of the company to get

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Update a company by ID

Update a company by ID

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
companyId
required
integer

ID of the company to update

Request Body schema: application/json
required
name
required
string

Name of the company

address
required
string

Address of the company

city
required
string

City of the company

country
required
string

Country of the company

phone
required
string

Phone number of the company

email
required
string

Email of the company

website
required
string

Website of the company

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Delete a company by ID

Delete a company by ID

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
companyId
required
integer

ID of the company to delete

Responses

Patch a company

Partially updates a company document with the provided fields and logs the admin action.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Company ObjectId

Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "Update Company successfully!"
}

Location

Get all locations

Get all locations

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
keyword
string

Get locations by name, address, etc.

page
integer

Page number

per_page
integer

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "total": 25,
  • "page": 1,
  • "data": [
    ]
}

Create a new location

Create a new location

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
name
required
string

Name of the location

longitude
required
number

Longitude of the location

latitude
required
number

Latitude of the location

status
required
string

Status of the location

description
required
string

Description of the location

address
required
string

Address of the location

region
required
string

Region of the location

city
required
string

City of the location

postal
required
string

Postal code of the location

country
required
string

Country code of the location

image
required
string

Image filename of the location

ChargePoints
Array of strings

List of ChargePoint IDs to add to the location

is_enabled
required
boolean

Whether the location is enabled

SeedingPartner
required
string

ID of the SeedingPartner

CPO
required
string

ID of the CPO

Responses

Request samples

Content type
application/json
{
  • "name": "Lake Life",
  • "longitude": 103.7240083,
  • "latitude": 1.3321456,
  • "status": "active",
  • "description": "2, 6, 8, 10, 12 Tao Ching Rd, Singapore 618721",
  • "address": "2, 6, 8, 10, 12 Tao Ching Rd, Singapore 618721",
  • "region": "West",
  • "city": "Singapore",
  • "postal": 618721,
  • "country": "SG",
  • "image": "dlRjgYZsxXu1jvNJnx.png",
  • "ChargePoints": [
    ],
  • "is_enabled": true,
  • "SeedingPartner": "645c9740c4aa3d518c24b232",
  • "CPO": "6331254696ec3fa15d1cb0f7"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Get a location by ID

Get a location by ID

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
locationId
required
integer

ID of the location to get

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Update a location by ID

Update a location by ID

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
locationId
required
integer

ID of the location to update

Request Body schema: application/json
required
name
required
string

Name of the location

longitude
required
number

Longitude of the location

latitude
required
number

Latitude of the location

status
required
string

Status of the location

description
required
string

Description of the location

address
required
string

Address of the location

region
required
string

Region of the location

city
required
string

City of the location

postal
required
string

Postal code of the location

country
required
string

Country code of the location

image
required
string

Image filename of the location

ChargePoints
Array of strings

List of ChargePoint IDs to add to the location

is_enabled
required
boolean

Whether the location is enabled

SeedingPartner
required
string

ID of the SeedingPartner

CPO
required
string

ID of the CPO

Responses

Request samples

Content type
application/json
{
  • "name": "Lake Life",
  • "longitude": 103.7240083,
  • "latitude": 1.3321456,
  • "status": "active",
  • "description": "2, 6, 8, 10, 12 Tao Ching Rd, Singapore 618721",
  • "address": "2, 6, 8, 10, 12 Tao Ching Rd, Singapore 618721",
  • "region": "West",
  • "city": "Singapore",
  • "postal": 618721,
  • "country": "SG",
  • "image": "dlRjgYZsxXu1jvNJnx.png",
  • "ChargePoints": [
    ],
  • "is_enabled": true,
  • "SeedingPartner": "645c9740c4aa3d518c24b232",
  • "CPO": "6331254696ec3fa15d1cb0f7"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Delete a location by ID

Delete a location by ID

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
locationId
required
integer

ID of the location to delete

Responses

Get number of location grouped by date within a specified date range

This API retrieves the total number of locations for each date within a specified date range (from_date to to_date). The sessions are counted and grouped by date based on the createdAt field.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
from_date
required
string <date>

The start date of the range to fetch data (in YYYY-MM-DD format).

to_date
required
string <date>

The end date of the range to fetch data (in YYYY-MM-DD format).

type
required
string <string>

The type of request

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Add restricted users to EVSEs

This endpoint adds restricted users to specific EVSEs associated with provided locations.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
string or Array of strings

A single user ID or an array of user IDs to restrict.

string or Array of strings

A single location ID or an array of location IDs.

Responses

Request samples

Content type
application/json
{
  • "user_ids": [
    ],
  • "location_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "message": "Restricted users have been updated successfully"
}

Enable subscription plans for charge points

Enables the given subscription plans on the specified charge points within locations.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
charge_point_ids
required
Array of strings
subscription_plans
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "charge_point_ids": [
    ],
  • "subscription_plans": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true
}

Export locations to Excel

Aggregates locations (scoped by the caller's role) with their charge points, CPO and seeding partner data and streams the result as an .xlsx (Location.xlsx) attachment.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
name
string
address
string
city
string
region
string
postal
string
country
string
cpo_sp_name
string
type
string
page
integer >= 1
per_page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": false,
  • "msg": "Something went wrong, please contact CS for supporting."
}

List location change logs

Returns the audit/change logs for locations from the charging service.

Authorizations:
(AuthorizationTokenAuthorizationRole)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Get location change logs by ID

Returns the audit/change logs for a specific location.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Get location statistics by type

Retrieve location statistics for the requested type within the specified date range. For location-occupancy-reports, from_date and to_date are interpreted as Asia/Singapore calendar dates to match the daily occupancy report generation job.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
from_date
required
string <date>

The start date of the range to fetch data (in YYYY-MM-DD format).

to_date
required
string <date>

The end date of the range to fetch data (in YYYY-MM-DD format).

type
required
string
Enum: "number-of-location" "location-occupancy-reports" "location-performance"

The statistics type to retrieve.

Responses

Response samples

Content type
application/json
{
  • "ok": false,
  • "msg": "invalid input",
  • "errors": [
    ]
}

Sync all location prices

Triggers the charging service to synchronise pricing across all locations.

Authorizations:
(AuthorizationTokenAuthorizationRole)

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Generate a location performance report

Generates a monthly performance report for the given location for the specified month and year.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string
Request Body schema: application/json
required
month
required
integer [ 1 .. 12 ]
year
required
integer

Responses

Request samples

Content type
application/json
{
  • "month": 1,
  • "year": 0
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Enable or disable queue for a location

Toggles the charging queue feature for the given location.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
location_id
required
string
Request Body schema: application/json
required
is_active
required
boolean

Responses

Request samples

Content type
application/json
{
  • "is_active": true
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Get multiple locations by IDs

Retrieve multiple locations in a single request by passing an array of their IDs. Soft-deleted locations are excluded; invalid or missing IDs yield an empty list.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
ids
required
Array of strings <objectId> [ items <objectId > ]

Array of location IDs (MongoDB ObjectIds) to fetch.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

User

Get all users

Retrieve a list of all users

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
page
integer

Page number

per_page
integer

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "total": 25,
  • "page": 1,
  • "data": [
    ]
}

Create a new user

Create a new user

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
name
required
string

Name of the user

email
required
string <email>

Email address of the user

password
required
string

Password for the user

phone
required
string

Phone number of the user

dob
string <date>

Date of birth of the user (optional)

vehicle_license_plate
required
string

Vehicle license plate of the user

vehicle_brand
required
string

Brand of the vehicle

vehicle_model
required
string

Model of the vehicle

Responses

Request samples

Content type
application/json
{
  • "name": "user1",
  • "email": "[email protected]",
  • "password": "password123",
  • "phone": "1234567890",
  • "dob": "1991-04-01",
  • "vehicle_license_plate": "ABC1234",
  • "vehicle_brand": "Toyota",
  • "vehicle_model": "Camry"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Get a user by ID

Get a user by their ID

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
userId
required
string

ID of the user to retrieve

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Update a user by ID

Update a user by their ID

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
userId
required
string

ID of the user to update

Request Body schema: application/json
required
name
string

Name of the user

email
string <email>

Email address of the user

password
string

Password for the user

phone
integer

Phone number of the user

dob
string <date>

Date of birth of the user

wallet_balance
integer

Current wallet balance of the user

vehicle_license_plate
string

License plate number of the user's vehicle

vehicle_brand
string

Brand of the user's vehicle

vehicle_model
string

Model of the user's vehicle

stripe_tokenized_cards
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "Tino",
  • "email": "[email protected]",
  • "password": "password123",
  • "phone": 827277157,
  • "dob": "1990-05-02T00:00:00.000Z",
  • "wallet_balance": 15931,
  • "vehicle_license_plate": "123456",
  • "vehicle_brand": "TESLA",
  • "vehicle_model": "123456",
  • "stripe_tokenized_cards": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Delete a user by ID

Delete a user by their ID

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
userId
required
string

ID of the user to delete

Responses

Get a user's point history

Retrieve the point history of a specific user

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
userId
required
string

ID of the user to retrieve point history for

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Add points to a user

Add points to a specific user's account

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
userId
required
string

ID of the user to add points to

Request Body schema: application/json
required
points
integer

Number of points to add to the user's account

Responses

Request samples

Content type
application/json
{
  • "points": 1000
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "message": "Points added successfully"
}

Update User's Subscription Auto Renew Setting

Allows updating the auto-renew setting for a specific user.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
user_id
required
string <objectid>

The unique identifier of the user (MongoDB ObjectId).

Request Body schema: application/json
required
subscription_auto_renew
required
boolean

Indicates whether the subscription should auto-renew.

Responses

Request samples

Content type
application/json
{
  • "subscription_auto_renew": true
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "message": "Update subscription auto renew for user successfully"
}

Get login token for a target user

Authenticates an authorizing admin using credentials provided in request headers, then returns the login token of the target user specified in the request body. The admin must exist and provide valid credentials. The target user must exist in the system.

Authorizations:
None
header Parameters
admin-email
required
string <email>

Email of the admin performing the authorization.

admin-password
required
string
Example: s3cur3P@ssw0rd

Password of the admin performing the authorization.

Request Body schema: application/json
required
email
required
string <email>

Email of the target user whose login token is being requested.

purpose
required
string

Reason for requesting the token. This is recorded in the audit log.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Export users to Excel

Fetches users from the user service (with optional filters) and returns an .xlsx spreadsheet as a downloadable attachment.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
name
string
email
string
phone
string
vehicle_license_plate
string
vehicle_brand
string
vehicle_model
string
per_page
integer >= 1
page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": false,
  • "msg": "invalid input",
  • "errors": [
    ]
}

Restore a deleted user

Restores a previously soft-deleted user and logs the admin action.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
user_id
required
string

User ObjectId

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Get user statistics

Returns user statistics by type (e.g. number of new users). Results are scoped to the requesting admin's role (Seeding Partner / CPO) and, when a date range is provided, missing dates are back-filled.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
type
required
string

Statistic type, e.g. by-number-of-new-users

from_date
string <date>

YYYY-MM-DD

to_date
string <date>

YYYY-MM-DD

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Top up a user's free credits

Adds free credit to a user's wallet via the payment service. The amount is converted to cents before being sent.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
amount
required
number

Amount greater than 0

description
required
string
user_id
required
string

User ObjectId

Responses

Request samples

Content type
application/json
{
  • "amount": 10,
  • "description": "Promo top-up",
  • "user_id": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "Topup successful",
  • "data": { }
}

Toggle user subscription auto-renew

Enables or disables auto-renew of the user's active subscription.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
user_id
required
string

User ObjectId

Request Body schema: application/json
required
subscription_auto_renew
required
boolean

Responses

Request samples

Content type
application/json
{
  • "subscription_auto_renew": true
}

Response samples

Content type
application/json
{
  • "ok": true
}

Get multiple users by IDs

Retrieve multiple users in a single request by passing an array of their IDs. Optional name/email/phone filters further narrow the matched users.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
ids
required
Array of strings <objectId> [ items <objectId > ]

Array of user IDs (MongoDB ObjectIds) to fetch.

name
string

Optional case-insensitive partial match on user name.

email
string

Optional case-insensitive partial match on user email.

phone
string

Optional case-insensitive partial match on user phone.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ],
  • "name": "John",
  • "email": "[email protected]",
  • "phone": "12345"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

PromoCodes

Get list promo codes programs with pagination

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
keyword
string

Search by keyword - code, name, ...

promo_type
string
Enum: "Subscription" "FeePayment"

Filter by promo type

status
string
Enum: "active" "inactive" "deleted"

Filter by status

is_used
boolean

Filter by is used

merchant_id
string

Filter by merchant id

page
integer

The page number.

per_page
integer

The numbers of items to return.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "total": 25,
  • "page": 1,
  • "data": [
    ]
}

Get promo codes

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Generate a list of promo codes. Promo program will be created automatically if not exist.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
program_id
string
number_of_codes
integer
start_date
string
end_date
string
status
string
discount_value
number
discount_type
string
Enum: "percent" "fixed"
max_discount
number

Maximum discount amount

max_discount_type
string
Enum: "percent" "fixed"

Responses

Request samples

Content type
application/json
{
  • "program_id": "665e8f15ebf7d56c133612ab",
  • "number_of_codes": 10,
  • "start_date": "2021-07-01T00:00:00.000Z",
  • "end_date": "2021-07-31T00:00:00.000Z",
  • "status": "active",
  • "discount_value": 100,
  • "discount_type": "percent",
  • "max_discount": 50,
  • "max_discount_type": "fixed"
}

Response samples

Content type
application/json
{
  • "ok": true
}

Generate a list of promo codes. Promo program will be created automatically if not exist.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
ids
Array of strings
promo_program_id
string

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ],
  • "promo_program_id": "667fced180a245c95d401f4c"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "message": "Invalidated {number} promo codes"
}

Extend Expiration.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
ids
Array of strings
promo_program_id
string
extend_to_date
string

date with format YYYY-MM-DD

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ],
  • "promo_program_id": "667fced180a245c95d401f4c",
  • "extend_to_date": "2028-07-31"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "message": "Expiration dates updated successfully"
}

Extend Expiration.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Promo Code ID

Request Body schema: application/json
required
amount
required
number
invoice_type
string

Responses

Request samples

Content type
application/json
{
  • "amount": 500000,
  • "invoice_type": "percent"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Assign a promo code to a user

Validates the user and promo code, then redeems (assigns) the specified promo code to the given user via the Promo Code service and records an admin activity log.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
user_id
required
string

ID of the user to assign the promo code to

promo_code_id
required
string

ID of the promo code to assign

Responses

Request samples

Content type
application/json
{
  • "user_id": "string",
  • "promo_code_id": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Export promo codes to Excel

Fetches promo codes from the Promo Code service matching the given filters and streams them back as an .xlsx spreadsheet download.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
keyword
string
code
string
promo_type
string
program_id
string
status
string
is_used
string
user_id
string
merchant_id
string
ids
string

Responses

Response samples

Content type
application/json
{
  • "ok": false,
  • "msg": "Something went wrong, please contact CS for supporting."
}

Backfill user info on promo codes

Maintenance job that iterates over promo codes missing denormalized user fields and backfills user_name, user_email, and user_phone from the users collection in batches.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
limit
integer
Default: 1000

Batch size per iteration

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "Processed all promocodes successfully"
}

PromoPrograms

Get list promo programs with pagination

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
keyword
string

Search by keyword - name, code, ...

merchant_id
string

Filter by merchant id

promo_type
string
Enum: "Subscription" "FeePayment"

Filter by promo type

used_codes
integer

Filter by used codes count

start_date
string <date-time>

Filter by start date

end_date
string <date-time>

Filter by end date

page
integer

The page number.

per_page
integer

The numbers of items to return.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "total": 25,
  • "page": 1,
  • "data": [
    ]
}

Create a new promo program

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
name
required
string
code
required
string <= 5 characters
merchant_id
required
string
description
string
start_date
required
string <date-time>
end_date
required
string <date-time>
promo_type
required
string
Enum: "Subscription" "FeePayment"
status
required
string
discount_value
required
integer
discount_type
required
string
max_discount
required
integer
max_discount_type
required
string
banner
string
term_of_use
string
detail
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "code": "strin",
  • "merchant_id": "string",
  • "description": "string",
  • "start_date": "2019-08-24T14:15:22Z",
  • "end_date": "2019-08-24T14:15:22Z",
  • "promo_type": "Subscription",
  • "status": "string",
  • "discount_value": 0,
  • "discount_type": "string",
  • "max_discount": 0,
  • "max_discount_type": "string",
  • "banner": "string",
  • "term_of_use": "string",
  • "detail": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "promoprograms": {
    }
}

Delete a promo program

Deletes the specified promo program via the Promo Code service and records an admin activity log with the previous state.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
promo_program_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Get promo program by ID

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
promo_program_id
required
string

Promo Program ID

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Update a promo program by ID

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
promo_program_id
required
string

Promo Program ID

Request Body schema: application/json
required
name
required
string
code
required
string <= 5 characters
merchant_id
required
string
description
string
start_date
required
string <date-time>
end_date
required
string <date-time>
promo_type
required
string
Enum: "Subscription" "FeePayment"
status
required
string
discount_value
required
integer
discount_type
required
string
max_discount
required
integer
max_discount_type
required
string
banner
string
term_of_use
string
detail
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "code": "strin",
  • "merchant_id": "string",
  • "description": "string",
  • "start_date": "2019-08-24T14:15:22Z",
  • "end_date": "2019-08-24T14:15:22Z",
  • "promo_type": "Subscription",
  • "status": "string",
  • "discount_value": 0,
  • "discount_type": "string",
  • "max_discount": 0,
  • "max_discount_type": "string",
  • "banner": "string",
  • "term_of_use": "string",
  • "detail": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "promoprograms": {
    }
}

Transactions

Get all transactions

Retrieve a list of transactions with optional filters.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
status
string

Filter by transaction status

user_id
string

Filter by user ID (must be a MongoDB ObjectId)

user_name
string

Filter by user name (supports partial match)

cpo_id
string

Filter by CPO ID (must be a MongoDB ObjectId)

cpo_name
string

Filter by CPO name (supports partial match)

sp_id
string

Filter by Seeding Partner ID (must be a MongoDB ObjectId)

sp_name
string

Filter by Seeding Partner name (supports partial match)

payment_type
string

Filter by payment type

type
string

Filter by transaction type

transaction_id
string

Filter by transaction ID

charge_session_id
string

Filter by charge session ID (must be a MongoDB ObjectId)

from_date
string <date>

Filter transactions from a specific date

to_date
string <date>

Filter transactions to a specific date

page
integer

The page number for pagination (default is 1)

per_page
integer

The number of items per page for pagination (default is 10)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "total": 100,
  • "page": 1,
  • "per_page": 10,
  • "data": [
    ]
}

Delete a transaction

Deletes the given transaction via the payment service, optionally recording a delete reason. Records an admin log entry capturing the previous state.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
transaction_id
required
string
Request Body schema: application/json
reason_delete
string

Responses

Request samples

Content type
application/json
{
  • "reason_delete": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "Transaction deleted successfully"
}

Get a transaction by ID

Retrieve a specific transaction by its ID.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
transaction_id
required
string

The ID of the transaction (must be a MongoDB ObjectId)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Get total deposit grouped by date within a specified date range

This API retrieves the total deposit of transaction for each date within a specified date range (from_date to to_date). The sessions are counted and grouped by date based on the createdAt field.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
from_date
required
string <date>

The start date of the range to fetch data (in YYYY-MM-DD format).

to_date
required
string <date>

The end date of the range to fetch data (in YYYY-MM-DD format).

type
required
string <string>

The type of request

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Get total number transaction grouped by date within a specified date range

This API retrieves the total of transaction for each date within a specified date range (from_date to to_date). The sessions are counted and grouped by date based on the createdAt field.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
from_date
required
string <date>

The start date of the range to fetch data (in YYYY-MM-DD format).

to_date
required
string <date>

The end date of the range to fetch data (in YYYY-MM-DD format).

type
required
string <string>

The type of request

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Manually charge or top up a user

Superadmin-only. Charges a user for a charge session or performs a wallet top up using the user's current card. For charge_session type, charge_session_id is required.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
type
required
string
Enum: "charge_session" "topup"
user_id
required
string

Mongo ObjectId of the user

charge_session_id
string

Required when type is charge_session

amount
required
number

Amount in dollars

reason
required
string

Responses

Request samples

Content type
application/json
{
  • "type": "charge_session",
  • "user_id": "string",
  • "charge_session_id": "string",
  • "amount": 0,
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "string"
}

Export transactions to Excel

Exports the filtered transaction list as an .xlsx file. CPO and Seeding Partner roles are automatically scoped to their own transactions.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
status
string
user_id
string
user_name
string
cpo_id
string
cpo_name
string
sp_id
string
sp_name
string
payment_type
string
type
string
transaction_id
string
charge_session_id
string
from_date
string <date>

YYYY-MM-DD

to_date
string <date>

YYYY-MM-DD

ids
string
page
integer >= 1
per_page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": false,
  • "msg": "invalid input",
  • "errors": [
    ]
}

Backfill denormalized fields on transactions

Maintenance job that iterates fee_charging transactions missing denormalized fields (user, charge point, EVSE, location names, fees) and populates them from their charge sessions.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
limit
integer
Default: 1000

Batch size per iteration.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "Processed all transactions successfully"
}

Get transaction statistics

Returns transaction statistics of a given type over an optional date range. Supported types are total-deposit and total-number-transaction. CPO and Seeding Partner roles are scoped to their own data.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
type
required
string
Enum: "total-deposit" "total-number-transaction"
from_date
string <date>

YYYY-MM-DD

to_date
string <date>

YYYY-MM-DD

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Get multiple transactions by IDs

Retrieve multiple transactions in a single request by passing an array of their IDs. Optional filters allow selecting specific fields and narrowing by type/status.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
ids
required
Array of strings <objectId> [ items <objectId > ]

Array of transaction IDs (MongoDB ObjectIds) to fetch.

selectFields
string

Optional comma-separated list of fields to include in each returned transaction.

type
string

Optional filter by transaction type.

status
string

Optional filter by transaction status.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ],
  • "selectFields": "amount,status,type",
  • "type": "deposit",
  • "status": "success"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

EVSEs

Get all EVSEs

Retrieve a list of all EVSEs with optional filters.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
status
string

Filter by EVSE status (e.g., active, inactive)

location
string

Filter by location name or ID

vip_user
string

Filter by VIP user ID (must be a MongoDB ObjectId)

from_date
string <date>

Filter EVSEs from a specific date

to_date
string <date>

Filter EVSEs to a specific date

is_queue_enabled
boolean

Filter EVSEs by whether they consume users from the location queue. When false, EVSEs with a false, null, or missing flag are returned.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "total": 50,
  • "data": [
    ]
}

Create a new EVSE

Create a new EVSE with the provided information.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
ampeco_evse_id
string

The AMPECO EVSE ID

current_type
string

The type of current for the EVSE

status
string

The status of the EVSE

hardware_status
string

The hardware status of the EVSE

network_id
string

The network ID for the EVSE

object
object
object
createdAt
string <date-time>

The date the EVSE was created

updatedAt
string <date-time>

The date the EVSE was last updated

is_enabled
boolean

Whether the EVSE is enabled

is_queue_enabled
boolean
Default: false

Whether this EVSE consumes users from the location queue.

active_subscription
boolean

Whether the EVSE has an active subscription

deletedAt
string <date-time>

The date the EVSE was deleted, if applicable

Responses

Request samples

Content type
application/json
{
  • "ampeco_evse_id": "string",
  • "current_type": "string",
  • "status": "string",
  • "hardware_status": "string",
  • "network_id": "string",
  • "ChargePoint": {
    },
  • "CPO": {
    },
  • "SeedingPartner": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "is_enabled": true,
  • "is_queue_enabled": true,
  • "active_subscription": true,
  • "deletedAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Delete an EVSE

Deletes the EVSE with the given ID via the charging service and records an admin log entry.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
evse_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Get an EVSE by ID

Retrieve a specific EVSE by its ID.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
evse_id
required
string

The ID of the EVSE (must be a MongoDB ObjectId)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Update an existing EVSE

Update an existing EVSE with the provided information.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
evse_id
required
string

The ID of the EVSE to update (must be a MongoDB ObjectId)

Request Body schema: application/json
required
ampeco_evse_id
string

The AMPECO EVSE ID

current_type
string

The type of current for the EVSE

status
string

The status of the EVSE

hardware_status
string

The hardware status of the EVSE

network_id
string

The network ID for the EVSE

object
object
object
createdAt
string <date-time>

The date the EVSE was created

updatedAt
string <date-time>

The date the EVSE was last updated

is_enabled
boolean

Whether the EVSE is enabled

is_queue_enabled
boolean
Default: false

Whether this EVSE consumes users from the location queue.

active_subscription
boolean

Whether the EVSE has an active subscription

deletedAt
string <date-time>

The date the EVSE was deleted, if applicable

_id
string

The unique identifier for the EVSE.

connectors
string

A list of connectors available for the EVSE.

idle_enters_reservation_fee
number

Fee charged when the EVSE enters reservation mode.

idle_grace_fee
number

Fee charged during the idle grace period.

idle_timing_0
number

Idle timing fee for time slot 0.

idle_timing_1
number

Idle timing fee for time slot 1.

idle_timing_2
number

Idle timing fee for time slot 2.

idle_timing_3
number

Idle timing fee for time slot 3.

idle_timing_4
number

Idle timing fee for time slot 4.

idle_timing_5
number

Idle timing fee for time slot 5.

idle_timing_6
number

Idle timing fee for time slot 6.

idle_timing_enabled
boolean

Whether idle timing is enabled for the EVSE.

max_a
number

Maximum current the EVSE can provide.

max_p
number

Maximum power the EVSE can provide.

max_v
number

Maximum voltage the EVSE can provide.

Responses

Request samples

Content type
application/json
{
  • "ampeco_evse_id": "string",
  • "current_type": "string",
  • "status": "string",
  • "hardware_status": "string",
  • "network_id": "string",
  • "ChargePoint": {
    },
  • "CPO": {
    },
  • "SeedingPartner": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "is_enabled": true,
  • "is_queue_enabled": true,
  • "active_subscription": true,
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "_id": "60d9f1145b9e3a1c4f9d8a45",
  • "connectors": [
    ],
  • "idle_enters_reservation_fee": 500,
  • "idle_grace_fee": 5,
  • "idle_timing_0": "07:00-23:00",
  • "idle_timing_1": "07:00-23:00",
  • "idle_timing_2": "07:00-23:00",
  • "idle_timing_3": "07:00-23:00",
  • "idle_timing_4": "07:00-23:00",
  • "idle_timing_5": "07:00-23:00",
  • "idle_timing_6": "07:00-23:00",
  • "idle_timing_enabled": true,
  • "max_a": 32,
  • "max_p": 22000,
  • "max_v": 400
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Get EVSE count grouped by date

Retrieve the count of EVSEs grouped by date within the specified time range. Filters are available for current type, hardware status, CPO, and Seeding Partner.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
from_date
required
string <date>

The start date of the range in YYYY-MM-DD format.

to_date
required
string <date>

The end date of the range in YYYY-MM-DD format.

current_type
string

The current type to filter EVSEs (e.g., AC or DC).

hardware_status
string

The hardware status to filter EVSEs (e.g., active or inactive).

type
required
string <string>

The type of request (e.g., number-evse)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Get EVSE counts grouped by date and status

Retrieve the count of EVSEs grouped by date and charger status (e.g., active, inactive) within the specified time range. Additional filters are available for CPO and Seeding Partner.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
from_date
required
string <date>

The start date of the range in YYYY-MM-DD format.

to_date
required
string <date>

The end date of the range in YYYY-MM-DD format.

type
required
string <string>

The type of request (e.g., number-charger-status)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Get total watt fee statistics by date and status

Retrieve statistics about the total watt fee (calculated as the count of EVSEs multiplied by a fee per unit, e.g., 50) grouped by date and charger status within the specified time range. Optional filters are available for CPO and Seeding Partner.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
from_date
required
string <date>

The start date of the range in YYYY-MM-DD format.

to_date
required
string <date>

The end date of the range in YYYY-MM-DD format.

type
required
string <string>

The type of request (e.g., total-watt-fee)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Get total expense statistics by date and status

Retrieve statistics about the total expense (calculated as the count of EVSEs multiplied by a fee per unit, e.g., 50) grouped by date and charger status within the specified time range. Optional filters are available for CPO and Seeding Partner.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
from_date
required
string <date>

The start date of the range in YYYY-MM-DD format.

to_date
required
string <date>

The end date of the range in YYYY-MM-DD format.

type
required
string <string>

The type of request (e.g., total-expense)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Add restricted users to EVSEs

This endpoint adds restricted users to specific EVSEs associated with provided locations.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
string or Array of strings

A single user ID or an array of user IDs to restrict.

string or Array of strings

A single evse ID or an array of evse IDs.

Responses

Request samples

Content type
application/json
{
  • "user_ids": [
    ],
  • "evse_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "message": "Restricted users have been updated successfully"
}

toggle on/off, edit subscription plans for EVSE

Using to subscription_price_enabled to toggle enable/disable subscription plan for EVSE

Using enable_subscription_plans to edit subscription plans for EVSE

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
evse_id
required
string

The ID of the EVSE (must be a MongoDB ObjectId)

Request Body schema: application/json
required
subscription_price_enabled
boolean

Using to toggle enable/disable subscription plan for EVSE

enable_subscription_plans
Array of strings

Responses

Request samples

Content type
application/json
{
  • "subscription_price_enabled": true,
  • "enable_subscription_plans": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Synchronize all EVSEs from Ampeco

Initiates a background synchronization of all EVSEs from Ampeco. If a synchronization is already in progress, the request will be rejected. The sync runs asynchronously — a 200 response only indicates the process has been started. A Slack notification is sent when the sync is initiated. The in-progress lock expires after 5 minutes.

Authorizations:
(AuthorizationTokenAuthorizationRole)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "Synchronization of all EVSEs has been initiated. This process may take some time to complete."
}

Export EVSEs to Excel

Builds and streams an Evse.xlsx spreadsheet of EVSEs matching the given filters. Seeding Partner and CPO roles are scoped to their own EVSEs.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
name
string
ampeco_evse_id
string
status
string
network_id
string
current_type
string
charge_point_id
string
cpo_sp_name
string
per_page
integer >= 1
page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": false,
  • "msg": "Something went wrong, please contact CS for supporting."
}

Export EVSE pricing to Excel

Fetches EVSE pricing from the charging service and streams an EvsePricing.xlsx spreadsheet. Seeding Partner and CPO roles are scoped to their own EVSEs.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
name
string
ampeco_evse_id
string
status
string
network_id
string
current_type
string
charge_point_id
string
cpo_sp_name
string

Responses

Response samples

Content type
application/json
{
  • "ok": false,
  • "msg": "Something went wrong, please contact CS for supporting."
}

Import EVSE pricing from Excel

Parses an uploaded XLSX file and updates EVSE pricing (price_normal_new, price_vip_new, tariff_new) via the charging service. Requires a multipart file upload under the file field.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: multipart/form-data
required
file
required
string <binary>

XLSX file with pricing rows

is_update_immediately
boolean

Apply the new prices immediately

apply_time
string

Scheduled time to apply the new prices

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "string"
}

List EVSE logs

Returns EVSE activity logs, proxied to the charging service.

Authorizations:
(AuthorizationTokenAuthorizationRole)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Get an EVSE log by ID

Returns a single EVSE log entry by its ID, proxied to the charging service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Remove restricted users from EVSEs

Removes restricted (VIP) users from the given EVSEs via the charging service and records an admin log entry.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
string or Array of strings
string or Array of strings

Responses

Request samples

Content type
application/json
{
  • "user_ids": "string",
  • "evse_ids": "string"
}

Response samples

Content type
application/json
{
  • "ok": true
}

List EVSE restricted (VIP) users

Returns the restricted-user (VIP) records for EVSEs, proxied to the charging service. Seeding Partner and CPO roles are automatically scoped to their own records.

Authorizations:
(AuthorizationTokenAuthorizationRole)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Get EVSE statistics by type

Returns EVSE statistics depending on the type parameter. Supported types include number-evse, number-charger-status, total-watt-fee, total-expense, current-status, total-restricted-users and by-charger. Seeding Partner and CPO roles are scoped to their own EVSEs.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
type
required
string
Enum: "number-evse" "number-charger-status" "total-watt-fee" "total-expense" "current-status" "total-restricted-users" "by-charger"
from_date
string <date>
to_date
string <date>
current_type
string
hardware_status
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Synchronize EVSE VIP list

Proxies the request to the charging service to synchronize each EVSE's VIP list.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "ok": true
}

Synchronize EVSE VIP users

Rebuilds the evsevipuser records from each EVSE's vip_list, enriching them with user and location details, and marks outdated entries as removed.

Authorizations:
(AuthorizationTokenAuthorizationRole)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "string"
}

Synchronize a single EVSE from Ampeco

Triggers synchronization of the given EVSE with Ampeco via the charging service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
evse_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Get top EVSEs by utilization rating

Returns the top EVSEs ranked by utilization rating for the given period, proxied to the charging service. Seeding Partner and CPO roles are scoped to their own EVSEs.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
limit
integer
rating_type
string
Enum: "daily" "weekly" "monthly"

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Backfill EVSE locations from charge points

Iterates over EVSEs missing a Location and sets it from their linked charge point, in batches.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
limit
integer

Batch size (default 50)

Responses

Request samples

Content type
application/json
{
  • "limit": 0
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "string"
}

Update a user's restricted EVSEs

Updates the set of EVSEs on which a single user is restricted (VIP), via the charging service, and records an admin log entry.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
user_id
required
string

The user to update (required)

string or Array of strings

Responses

Request samples

Content type
application/json
{
  • "user_id": "string",
  • "evse_ids": "string"
}

Response samples

Content type
application/json
{
  • "ok": true
}

Update VIP data at EVSEs

Proxies the request body to the charging service to update VIP data on EVSEs.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "ok": true
}

Generate an EVSE performance report

Generates a performance report for the given EVSE and month/year via the charging service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string
Request Body schema: application/json
required
month
required
integer [ 1 .. 12 ]

Report month (1-12)

year
required
integer

Report year

Responses

Request samples

Content type
application/json
{
  • "month": 1,
  • "year": 0
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Get multiple EVSEs by IDs

Retrieve multiple EVSEs in a single request by passing an array of their IDs.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
ids
required
Array of strings <objectId> [ items <objectId > ]

Array of EVSE IDs (MongoDB ObjectIds) to fetch.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Informations

Retrieve a list of informations

Fetch a list of information records with optional filters and pagination.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
title
string

Filter by title (case-insensitive regex search)

is_active
boolean

Filter by active status

per_page
integer <int32>
Example: per_page=10

Number of records per page

page
integer <int32>
Example: page=1

Page number for pagination

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ],
  • "total": 100,
  • "page": 1,
  • "per_page": 10
}

Create a new information record

Create a new information record with the provided data.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
title
string
content
string
icon
string
background
string
InformationCategory
string <objectId>
is_active
boolean
description
string

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "content": "string",
  • "icon": "string",
  • "background": "string",
  • "InformationCategory": "string",
  • "is_active": true,
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Retrieve a specific information by ID

Fetch a single information record by its ID.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
information_id
required
string <objectId>

ID of the information to retrieve

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Update an existing information record

Update information details using the provided data.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
information_id
required
string <objectId>

ID of the information to update

Request Body schema: application/json
required
title
string
content
string
icon
string
background
string
InformationCategory
string <objectId>
is_active
boolean
description
string

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "content": "string",
  • "icon": "string",
  • "background": "string",
  • "InformationCategory": "string",
  • "is_active": true,
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "Update information successfully"
}

Delete an information record

Mark an information record as deleted by setting the deletedAt field.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
information_id
required
string <objectId>

ID of the information to delete

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "Delete information successfully!"
}

InformationCategories

Retrieve a list of information categories

Fetch a list of information category records with optional filters and pagination.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
name
string

Filter by category name (case-insensitive regex search)

type
string

Filter by category type (case-insensitive regex search)

is_active
boolean

Filter by active status

per_page
integer <int32>
Example: per_page=10

Number of records per page

page
integer <int32>
Example: page=1

Page number for pagination

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ],
  • "total": 100,
  • "page": 1,
  • "per_page": 10
}

Create a new information category

Create a new information category with the provided data.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
name
string
description
string
type
string
is_active
boolean
thumbnail
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "type": "string",
  • "is_active": true,
  • "thumbnail": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "category": {
    }
}

Retrieve a specific information category by ID

Fetch a single information category record by its ID.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
category_id
required
string <objectId>

ID of the category to retrieve

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Update an existing information category

Update category details using the provided data.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
category_id
required
string <objectId>

ID of the category to update

Request Body schema: application/json
required
name
string
description
string
type
string
is_active
boolean
thumbnail
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "type": "string",
  • "is_active": true,
  • "thumbnail": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "Update category successfully"
}

Delete an information category

Mark an information category record as deleted by setting the deletedAt field.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
category_id
required
string <objectId>

ID of the category to delete

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "Delete category successfully!"
}

Upload

Upload a file

Upload a single file to a specific schema folder. The returned link is a CDN URL for the uploaded file.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
schema
required
string
Example: rewards-programs

Schema folder to upload into (information, information-category, avatar, rewards-programs, etc.)

Request Body schema: multipart/form-data
required
file
required
string <binary>

Responses

Response samples

Content type
application/json
{}

Admin

Retrieve List CPO and SP in admins

Fetches data for admins with roles of CPO or SP based on optional query parameters.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
name
string

Name to filter.

email
string

Email to filter.

type
string

Type to filter the results by.

role_id
string <objectID>

Role ID to filter the results by. Must be a valid MongoDB ObjectId.

company_id
string <objectID>

Company ID to filter the results by. Must be a valid MongoDB ObjectId.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ],
  • "total": 100,
  • "page": 1,
  • "per_page": 10
}

Create an admin

Creates an admin account. Resolves the given role name to a Role reference, encrypts the password, and validates profit-sharing splits (must total 0 or 1).

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
name
required
string >= 3 characters
email
required
string <email>
password
required
string
type
string
Enum: "commercial" "residential" "industrial" "government"
role
string
acSubscriptionFee
number
dcSubscriptionFee
number
platformProfitSharing
number [ 0 .. 1 ]
cpoProfitSharing
number [ 0 .. 1 ]
spProfitSharing
number [ 0 .. 1 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "email": "[email protected]",
  • "password": "string",
  • "type": "commercial",
  • "role": "string",
  • "acSubscriptionFee": 0,
  • "dcSubscriptionFee": 0,
  • "platformProfitSharing": 1,
  • "cpoProfitSharing": 1,
  • "spProfitSharing": 1
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "Admin created successfully",
  • "admin": {
    }
}

Get a list of admins

Retrieve a list of admins based on filters, pagination, and role information.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
name
string

Filter by admin name (case-insensitive, partial match).

email
string

Filter by admin email (case-insensitive, partial match).

ids
string

Comma-separated list of admin IDs to filter by.

is_active
boolean

Filter by active status.

role_names
string

Comma-separated list of role names to filter by.

per_page
integer
Default: 10

Number of records per page for pagination (default is 10).

page
integer
Default: 1

Page number for pagination (default is 1).

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ],
  • "total": 50,
  • "page": 1,
  • "per_page": 10
}

Get login token for a target admin

Authenticates an authorizing admin using credentials provided in request headers, then returns the login token of the target admin specified in the request body. Both the authorizing admin and the target admin must exist in the system.

Authorizations:
None
header Parameters
admin-email
required
string <email>

Email of the admin performing the authorization.

admin-password
required
string
Example: s3cur3P@ssw0rd

Password of the admin performing the authorization.

Request Body schema: application/json
required
email
required
string <email>

Email of the target admin whose login token is being requested.

purpose
required
string

Reason for requesting the token. This is recorded in the audit log.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Change admin password via OTP

Sets a new password for an admin after verifying the OTP. password and confirm_password must match.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
email
required
string <email>
otp
required
string
password
required
string
confirm_password
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "[email protected]",
  • "otp": "string",
  • "password": "string",
  • "confirm_password": "string"
}

Response samples

Content type
application/json
{
  • "ok": true
}

List CPO and SP admins

Returns admins filtered to CPO / Seeding Partner roles, with pagination and filters.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
name
string
email
string
type
string
role_id
string
company_id
string
ids
string
page
integer >= 1
per_page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Request admin password reset

Initiates a password reset for the admin with the given email (sends an OTP).

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
email
required
string <email>

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "ok": true
}

Verify admin OTP

Verifies a one-time password issued during the admin password-reset flow.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
email
required
string <email>
otp
required
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "ok": true
}

Get an admin by ID

Returns a single admin by its ObjectId.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Admin ObjectId

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Update an admin

Updates an admin's profile. Resolves role name to a Role reference, encrypts a new password if given, and validates that profit-sharing splits total 0 or 1.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Admin ObjectId

Request Body schema: application/json
name
string >= 3 characters
email
string <email>
password
string >= 6 characters
type
string
Enum: "commercial" "residential" "industrial" "government"
role
string
acSubscriptionFee
number
dcSubscriptionFee
number
platformProfitSharing
number [ 0 .. 1 ]
cpoProfitSharing
number [ 0 .. 1 ]
spProfitSharing
number [ 0 .. 1 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "email": "[email protected]",
  • "password": "string",
  • "type": "commercial",
  • "role": "string",
  • "acSubscriptionFee": 0,
  • "dcSubscriptionFee": 0,
  • "platformProfitSharing": 1,
  • "cpoProfitSharing": 1,
  • "spProfitSharing": 1
}

Response samples

Content type
application/json
{
  • "ok": true
}

Patch an admin's company/location

Partially updates an admin, mapping company_id and location_id to their Company / Location references.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Admin ObjectId

Request Body schema: application/json
company_id
string

Company ObjectId

location_id
string

Location ObjectId

Responses

Request samples

Content type
application/json
{
  • "company_id": "string",
  • "location_id": "string"
}

Response samples

Content type
application/json
{
  • "ok": true
}

Delete an admin

Deletes an admin by its ObjectId.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Admin ObjectId

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Get multiple admins by IDs

Retrieve multiple admins (each with their populated role) in a single request by passing an array of their IDs. Soft-deleted admins are excluded.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
ids
required
Array of strings <objectId> [ items <objectId > ]

Array of admin IDs (MongoDB ObjectIds) to fetch.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

ChargePoint

Retrieve a list of Charge Points

Retrieve a list of Charge Points with optional filters and pagination.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
name
string

Filter by name (case-insensitive regex search)

ampeco_chargepoint_id
string

Filter by ampeco_chargepoint_ids

status
string

Filter by status

network_status
string

Filter by network_status

is_enabled
boolean

Filter by is_enabled

access_type
boolean

Filter by access_type

cpo_id
string <ObjectID>

Filter by CPO _id

sp_id
string <ObjectID>

Filter by SP _id

location_id
string <ObjectID>

Filter by Location _id

from_date
string <date-time>

Filter ChargePoint was created from from_date (ISO8601, YYYY-MM-DD)

to_date
string <date-time>

Filter ChargePoint was created before to_date (ISO8601, YYYY-MM-DD)

per_page
integer <int32>
Example: per_page=10

Number of records per page

page
integer <int32>
Example: page=1

Page number for pagination

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ],
  • "total": 100,
  • "page": 1,
  • "per_page": 10
}

Create a new charge point

Creates a new charge point in the system with the provided details.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
name
required
string

Name of the charge point.

ampeco_chargepoint_id
required
string

Ampeco charge point ID.

Evse
required
Array of strings <ObjectID> [ items <ObjectID > ]

List of EVSE IDs associated with the charge point.

Location
required
string

ID of the location where the charge point is installed.

CPO
required
string

ID of the CPO (Charge Point Operator) responsible for the charge point.

status
required
string

Status of the charge point.

access_type
required
string

Access type of the charge point.

network_id
required
string

Network ID to which the charge point belongs.

network_protocol
required
string

Network protocol used by the charge point.

charge_speed
required
integer

Charge speed of the charge point in kW.

network_status
required
string

Current network status of the charge point.

subscription_price_enabled
required
boolean

Indicates if subscription price is enabled for this charge point.

reservation_enabled
required
boolean

Indicates if the reservation function is enabled.

reservation_same_day
required
boolean

Indicates if same-day reservations are allowed.

reservation_block
integer

Grace period (block) for the reservation in minutes.

reservation_cancel_grace_period
integer

Cancellation grace period in minutes.

reservation_grace_period
integer

Maximum reservation period in minutes.

reservation_deposit_amount
number <float>

Deposit amount for the reservation.

idle_enters_reservation_fee
number <float>

Idling fee charged when a reserved charge point is not utilized.

idle_timing_enabled
boolean

Indicates if the idling penalty function is enabled.

idle_grace_period
integer

Grace period for idling in minutes.

idle_grace_fee
number <float>

Idling penalty fee charged after the grace period.

idle_timing_0
string

Custom idling timing for Sunday in the format HH:mm-HH:mm.

idle_timing_1
string

Custom idling timing for Monday in the format HH:mm-HH:mm.

idle_timing_2
string

Custom idling timing for Tuesday in the format HH:mm-HH:mm.

idle_timing_3
string

Custom idling timing for Wednesday in the format HH:mm-HH:mm.

idle_timing_4
string

Custom idling timing for Thursday in the format HH:mm-HH:mm.

idle_timing_5
string

Custom idling timing for Friday in the format HH:mm-HH:mm.

idle_timing_6
string

Custom idling timing for Saturday in the format HH:mm-HH:mm.

price_vip
required
number <float>

Pricing for public users.

price_normal
required
number <float>

Pricing for restricted users.

tariff
required
number <float>

Electrical tariff rate.

Responses

Request samples

Content type
application/json
{
  • "name": "TinoCPO",
  • "ampeco_chargepoint_id": "147",
  • "Evse": [
    ],
  • "Location": "605c72ef1f1a2d3d9e5a7b2c",
  • "CPO": "605c72ef1f1a2d3d9e5a7b2d",
  • "status": "active",
  • "access_type": "public",
  • "network_id": "network-001",
  • "network_protocol": "OCPP 2.0",
  • "charge_speed": 50,
  • "network_status": "long-term unavailable",
  • "subscription_price_enabled": true,
  • "reservation_enabled": true,
  • "reservation_same_day": true,
  • "reservation_block": 15,
  • "reservation_cancel_grace_period": 30,
  • "reservation_grace_period": 120,
  • "reservation_deposit_amount": 10.5,
  • "idle_enters_reservation_fee": 2.5,
  • "idle_timing_enabled": true,
  • "idle_grace_period": 10,
  • "idle_grace_fee": 1.5,
  • "idle_timing_0": "07:00-10:00",
  • "idle_timing_1": "07:00-10:00",
  • "idle_timing_2": "07:00-10:00",
  • "idle_timing_3": "07:00-10:00",
  • "idle_timing_4": "07:00-10:00",
  • "idle_timing_5": "07:00-10:00",
  • "idle_timing_6": "07:00-10:00",
  • "price_vip": 5,
  • "price_normal": 3,
  • "tariff": 0.2
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "chargepoint": {
    }
}

Retrieve a specific ChargePoint by ID

Fetch a single ChargePoint record by its ID.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
charge_point_id
required
string
Example: 605c72ef1f1a2d3d9e5a7b2e

The ID of the charge point to update.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Update an existing charge point

Updates the details of a charge point specified by the ID.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
charge_point_id
required
string
Example: 605c72ef1f1a2d3d9e5a7b2e

The ID of the charge point to update.

Request Body schema: application/json
optional
name
string

Name of the charge point.

ampeco_chargepoint_id
string

Ampeco charge point ID.

Evse
Array of strings

List of EVSE IDs associated with the charge point.

Location
string

ID of the location where the charge point is installed.

CPO
string

ID of the CPO (Charge Point Operator) responsible for the charge point.

status
string

Status of the charge point.

access_type
string

Access type of the charge point.

network_id
string

Network ID to which the charge point belongs.

network_protocol
string

Network protocol used by the charge point.

charge_speed
integer

Charge speed of the charge point in kW.

network_status
string

Current network status of the charge point.

subscription_price_enabled
boolean

Indicates if subscription price is enabled for this charge point.

Responses

Request samples

Content type
application/json
{
  • "name": "ChargePoint Name",
  • "ampeco_chargepoint_id": "197",
  • "Evse": [
    ],
  • "Location": "605c72ef1f1a2d3d9e5a7b2c",
  • "CPO": "605c72ef1f1a2d3d9e5a7b2d",
  • "status": "active",
  • "access_type": "public",
  • "network_id": "network-001",
  • "network_protocol": "OCPP 2.0",
  • "charge_speed": 50,
  • "network_status": "long-term unavailable",
  • "subscription_price_enabled": true
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "Charge point updated successfully"
}

Delete charge point by ID

Delete a charge point by ID

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
charge_point_id
required
integer

ID of the charge point to delete

Responses

Enable subscription plans for a specified charge point.

This endpoint enables subscription plans for a specified charge point identified by either its ID or name.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
One of
charge_point_id
required
string

The unique identifier of the charge point (ObjectId).

charge_point_name
string

The name of the charge point.

subscription_plans
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "charge_point_id": "string",
  • "charge_point_name": "string",
  • "subscription_plans": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Enable subscription plans for charge points excluding specified IDs or names.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
One of
charge_point_names
Array of strings

An array of charge point names to exclude.

charge_point_ids
required
Array of strings

An array of charge point IDs to exclude (either ObjectId or ampeco_chargepoint_id).

subscription_plans
required
Array of strings

An array of subscription plan IDs to enable.

Responses

Request samples

Content type
application/json
{
  • "charge_point_names": [
    ],
  • "charge_point_ids": [
    ],
  • "subscription_plans": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "Subscription plans enabled for all ChargePoints except excluded IDs/names"
}

Enable multiple subscription plans for multiple specified charge points.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
One of
charge_point_names
Array of strings

An array of charge point names to include.

charge_point_ids
required
Array of strings

An array of charge point IDs to include (either ObjectId or ampeco_chargepoint_id).

subscription_plans
required
Array of strings

An array of subscription plan IDs to enable.

Responses

Request samples

Content type
application/json
{
  • "charge_point_names": [
    ],
  • "charge_point_ids": [
    ],
  • "subscription_plans": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "3 chargepoints updated"
}

Add restricted users to EVSEs

This endpoint adds restricted users to specific EVSEs associated with provided locations.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
string or Array of strings

A single user ID or an array of user IDs to restrict.

string or Array of strings

A single charge points ID or an array of charge points IDs.

Responses

Request samples

Content type
application/json
{
  • "user_ids": [
    ],
  • "charge_point_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "message": "Restricted users have been updated successfully"
}

Sync EVSEs of a charge point from Ampeco

Triggers the charging service to sync the EVSEs of the given Ampeco charge point.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
ampeco_chargepoint_id
required
string

Responses

Request samples

Content type
application/json
{
  • "ampeco_chargepoint_id": "string"
}

Response samples

Content type
application/json
{
  • "ok": true
}

Export charge points to Excel

Fetches charge points from the charging service using the same filters as the list endpoint and streams the result as an .xlsx (ChargePoint.xlsx) attachment.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
name
string
ampeco_chargepoint_id
string
status
string
network_status
string
is_enabled
boolean
access_type
string
cpo_id
string
sp_id
string
location_id
string
from_date
string <date>
to_date
string <date>
page
integer >= 1
per_page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": false,
  • "msg": "invalid input",
  • "errors": [
    ]
}

List charge point change logs

Returns the audit/change logs for charge points from the charging service.

Authorizations:
(AuthorizationTokenAuthorizationRole)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Get charge point change logs by ID

Returns the audit/change logs for a specific charge point.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Sync all charge point prices

Triggers the charging service to synchronise pricing for all charge points.

Authorizations:
(AuthorizationTokenAuthorizationRole)

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Queue

Get charging status for EVSEs in a location

Retrieve the charging status of all EVSEs associated with a specific location.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
location_id
required
string
Example: 6331276a96ec3fa15d1cb0fc

The ID of the location to filter EVSEs by.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

List queues

Returns a paginated list of queues with associated user data populated.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
page
integer >= 1
per_page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Remove a user from a queue

Cancels a user's place in the queue at a location on behalf of an admin.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
user_id
required
string
location_id
required
string

Responses

Request samples

Content type
application/json
{
  • "user_id": "string",
  • "location_id": "string"
}

Response samples

Content type
application/json
{
  • "ok": true
}

Advance the next waiting queue

Triggers processing of the next waiting entry in the queue.

Authorizations:
(AuthorizationTokenAuthorizationRole)

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Add a user to a queue

Adds a user to the queue at a location on behalf of an admin.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
user_id
required
string
location_id
required
string

Responses

Request samples

Content type
application/json
{
  • "user_id": "string",
  • "location_id": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Get queue statistics

Returns queue statistics of the given type (total-queuing-turns or total-missed-leave-queuing). When a date range is supplied, missing dates are filled in.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
type
required
string
Enum: "total-queuing-turns" "total-missed-leave-queuing"

Statistic type.

from_date
string <date>

YYYY-MM-DD

to_date
string <date>

YYYY-MM-DD

location_id
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Get queue for a location

Returns the current queue for the given location.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
location_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Charge Session

Get number of charge sessions grouped by date within a specified date range

This API retrieves the total number of charge sessions for each date within a specified date range (from_date to to_date). The sessions are counted and grouped by date based on the createdAt field. Upcoming, canceled, no-show, and deleted sessions are excluded.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
from_date
required
string <date>

The start date of the range to fetch data (in YYYY-MM-DD format).

to_date
required
string <date>

The end date of the range to fetch data (in YYYY-MM-DD format).

type
required
string <string>

The type of request (e.g., number-of-sessions)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Get total idling fee from charge sessions grouped by date within a specified date range

This API retrieves the total idling fee from charge sessions for each date within a specified date range (from_date to to_date). The idling fee is summed and grouped by the session_ended_at field.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
from_date
required
string <date>

The start date of the range to fetch data (in YYYY-MM-DD format).

to_date
required
string <date>

The end date of the range to fetch data (in YYYY-MM-DD format).

type
required
string <string>

The type of request (e.g., idling-revenue)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Get utilization rate for each date within a specified date range

This API retrieves a simulated utilization rate (random values between 40 and 100) for each date within a specified date range (from_date to to_date). The utilization rate is returned for each day in the range based on the provided dates.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
from_date
required
string <date>

The start date of the range to fetch data (in YYYY-MM-DD format).

to_date
required
string <date>

The end date of the range to fetch data (in YYYY-MM-DD format).

type
required
string <string>

The type of request (e.g., charger-utilization)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Get total session revenue grouped by date within a specified date range

This API retrieves the total revenue for each date within a specified date range (from_date to to_date). The revenue is calculated by summing up the total_with_gst for each session, grouped by the createdAt field. Upcoming, canceled, no-show, and deleted sessions are excluded.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
from_date
required
string <date>

The start date of the range to fetch data (in YYYY-MM-DD format).

to_date
required
string <date>

The end date of the range to fetch data (in YYYY-MM-DD format).

type
required
string <string>

The type of request (e.g., charging-revenue)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Get total earnings grouped by date

Retrieve the total earnings for charge sessions grouped by date within the specified time range.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
from_date
required
string <date>

The start date of the range in YYYY-MM-DD format.

to_date
required
string <date>

The end date of the range in YYYY-MM-DD format.

type
required
string <string>

The type of request (e.g., total-earning)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Get total reservation no-show statistics by date

Retrieve statistics of reservations that were marked as "no-show" or "canceled" within a specified date range. Results are grouped by date, showing the count of such sessions for each date.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
from_date
required
string <date>

The start date of the range in YYYY-MM-DD format.

to_date
required
string <date>

The end date of the range in YYYY-MM-DD format.

type
required
string <string>

The type of request (e.g., total-reservation-no-show)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Get total charging duration statistics by date

Retrieve the total charging duration for charge sessions grouped by date within the specified time range.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
from_date
required
string <date>

The start date of the range in YYYY-MM-DD format.

to_date
required
string <date>

The end date of the range in YYYY-MM-DD format.

type
required
string <string>

The type of request (e.g., charging-duration)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

List charge sessions

Returns a paginated list of charge sessions, enriched with user, CPO/seeding-partner, transaction, EVSE and reward data. Seeding Partner and CPO roles are automatically scoped to their own sessions.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
status
string
user_id
string
user_name
string
cpo_id
string
cpo_name
string
sp_id
string
sp_name
string
type
string
charge_point_id
string
charge_point_name
string
location
string
location_id
string
from_date
string <date>

Start date filter, format YYYY-MM-DD.

to_date
string <date>

End date filter, format YYYY-MM-DD.

ids
string
page
integer >= 1
per_page
integer >= 1
sort_by
string
Enum: "session_started_at" "session_ended_at" "idling_started_at" "createdAt" "updatedAt"
sort_order
string
Enum: "asc" "desc"

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Apply tallied energy from Ampeco

Proxies to the charging service to apply tallied energy values sourced from Ampeco to charge sessions.

Authorizations:
(AuthorizationTokenAuthorizationRole)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Check charge session data against Ampeco

Proxies to the charging service to compare local charge session data against Ampeco records.

Authorizations:
(AuthorizationTokenAuthorizationRole)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Charge a fee against a session

Charges a manual fee amount to a user for a given charge session via the charging service. The amount is converted to cents before being forwarded.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
user_id
required
string
charge_session_id
required
string
amount
required
number

Responses

Request samples

Content type
application/json
{
  • "user_id": "string",
  • "charge_session_id": "string",
  • "amount": 0
}

Response samples

Content type
application/json
{
  • "ok": true
}

Export charge sessions to Excel

Returns an XLSX file of charge sessions matching the given filters. Seeding Partner and CPO roles are automatically scoped to their own sessions.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
status
string
user_id
string
user_name
string
cpo_id
string
cpo_name
string
sp_id
string
sp_name
string
type
string
charge_point_id
string
charge_point_name
string
location
string
location_id
string
from_date
string <date>
to_date
string <date>
page
integer >= 1
per_page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": false,
  • "msg": "invalid input",
  • "errors": [
    ]
}

Fix January energy values

One-off maintenance endpoint that proxies to the charging service to correct energy values for January sessions.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "ok": true
}

Auto-flush hanging charge sessions

Triggers the charging service job that automatically flushes hanging (stuck) charge sessions.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "ok": true
}

Backfill charging duration on completed sessions

Maintenance job that iterates completed charge sessions missing duration fields and backfills charging_duration, total_charging_duration and denormalized user fields.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
limit
integer
Default: 1000

Batch size per iteration.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "string"
}

Backfill charger/location names on sessions

Maintenance job that backfills charger_name, charge_point_name and location_name on charge sessions missing them, by looking up related EVSE, charge point and location records.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
limit
integer
Default: 1000

Batch size per iteration.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "string"
}

Get charge session statistics by type

Returns aggregated charge session statistics for the given type (e.g. number of sessions, idling revenue, charger utilization, charging revenue, total earning, energy supplied). Supports optional date range and location scoping; Seeding Partner and CPO roles are scoped to their own data.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
type
required
string

Statistic type to compute.

from_date
string <date>
to_date
string <date>
skip_missing_dates
boolean
location_id
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Update session energy from Ampeco

Refreshes tallied energy for completed charge sessions from Ampeco. Either targets a list of IDs or a filtered/paginated set of completed sessions.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
from_date
string <date>
to_date
string <date>
ids
Array of strings
page
integer
per_page
integer

Responses

Request samples

Content type
application/json
{
  • "from_date": "2019-08-24",
  • "to_date": "2019-08-24",
  • "ids": [
    ],
  • "page": 0,
  • "per_page": 0
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "string"
}

Fix sessions with 1970/NaN duration

Repairs charge sessions in the given date range that have NaN charging_duration or an epoch (1970) session_stopped_at, by re-reading energy and timing data from Ampeco.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
from_date
required
string <date>
to_date
required
string <date>

Responses

Request samples

Content type
application/json
{
  • "from_date": "2019-08-24",
  • "to_date": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "string"
}

Update transaction energy for a month's sessions

Recomputes and reconciles per-transaction energy for completed sessions in a given month/year (optionally scoped to a location) that have multiple fee_charging transactions.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
month
required
integer [ 1 .. 12 ]
year
required
integer >= 2000
location_id
string

Responses

Request samples

Content type
application/json
{
  • "month": 1,
  • "year": 2000,
  • "location_id": "string"
}

Response samples

Content type
application/json
{
  • "ok": true
}

Calculate a session by Ampeco session ID

Recalculates and settles a charge session identified by its Ampeco session ID, provided it has no existing fee_charging transaction. Marks the session flushed and triggers payment.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
ampeco_session_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Preview energy settlement for a session

Computes an energy settlement for the given charge session (dry run) via the charging service and records an admin activity log.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
charge_session_id
required
string
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Apply energy settlement for a session

Applies the energy settlement for the given charge session via the charging service and records an admin activity log.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
charge_session_id
required
string
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Get a charge session by ID

Returns a single charge session with joined CPO and seeding-partner details. Seeding Partner and CPO roles can only access their own sessions.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
session_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "string",
  • "data": { }
}

Create a pending transaction for a session

Creates a pending transaction for the given charge session via the charging service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
session_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Flush a charge session from admin portal

Force-flushes an active/holding/pending charge session: marks it as flushed, triggers payment processing using the user's default payment method, and advances the EVSE queue.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
session_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "string"
}

Trigger payment for a session

Triggers payment processing for an unpaid charge session from the admin portal, using the user's default payment method. Reverts the session to completed/unpaid if payment fails.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
session_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

List charge sessions (aggregated)

Returns a paginated list of charge sessions built via a MongoDB aggregation with joined user, CPO, seeding-partner and charge point/location data. Seeding Partner and CPO roles are automatically scoped to their own sessions.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
status
string
user_id
string
user_name
string
cpo_id
string
cpo_name
string
sp_id
string
sp_name
string
charge_point_id
string
charge_point_name
string
location
string
location_id
string
from_date
string <date>
to_date
string <date>
page
integer >= 1
per_page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ],
  • "total": 0,
  • "page": 0,
  • "per_page": 0
}

Sync vehicle info for charge sessions

Triggers the charging service to sync vehicle information onto charge sessions.

Authorizations:
(AuthorizationTokenAuthorizationRole)

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Stop a charge session

Stops an active charge session by proxying to the charging service stop endpoint.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
charge_session_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Get a charge session by ID (aggregated)

Returns a single charge session with joined CPO and seeding-partner details. Seeding Partner and CPO roles can only access their own sessions.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
session_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "string",
  • "data": { }
}

Get multiple charge sessions by IDs

Retrieve multiple charge sessions in a single request by passing an array of their IDs. Each returned session is enriched with its related Evse, ChargePoint, and Location details. Soft-deleted sessions are excluded; an empty or missing ids array returns an empty list.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
ids
required
Array of strings <objectId> [ items <objectId > ]

Array of charge session IDs (MongoDB ObjectIds) to fetch.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Performance Reports

Retrieve performance reports for a specific type.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
type
required
string
Enum: "evse" "location"

The type of the report (evse, location).

query Parameters
evse_id
string <uuid>

EVSE ID.

charge_point_id
string <uuid>

Charge point ID.

location_id
string <uuid>

Location ID.

evse_name
string

Name of the EVSE.

charge_point_name
string

Name of the charge point.

location_name
string

Name of the location.

cpo_name
string

Name of the CPO.

sp_name
string

Name of the Seeding Partner.

month
integer [ 1 .. 12 ]

Month for the report.

year
integer >= 2000

Year for the report.

cpo_email
string <email>

Email of the CPO.

sp_email
string <email>

Email of the Seeding Partner.

per_page
integer >= 1

Number of reports per page.

page
integer >= 1

Page number for pagination.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Create a new performance report for a specific type.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
type
required
string
Enum: "evse" "location"

The type of the report (evse, location).

Request Body schema: application/json
required
month
integer

Month for the report (1-12).

year
integer

Year for the report (>= 2000).

location_id
string <uuid>

Location ID (valid MongoDB ID).

cpo_id
string <uuid>

CPO ID (valid MongoDB ID).

evse_id
string <uuid>

EVSE ID (optional, valid MongoDB ID).

evse_name
string

Name of the EVSE (optional).

charge_point_id
string <uuid>

Charge point ID (optional, valid MongoDB ID).

charge_point_name
string

Name of the charge point (optional).

location_name
string

Name of the location (optional).

cpo_name
string

Name of the CPO (optional).

cpo_email
string <email>

Email of the CPO (optional).

cpo_phone
string

Phone number of the CPO (optional).

sp_id
string <uuid>

Seeding Partner ID (optional, valid MongoDB ID).

sp_name
string

Name of the Seeding Partner (optional).

sp_email
string <email>

Email of the Seeding Partner (optional).

sp_phone
string

Phone number of the Seeding Partner (optional).

number_of_charge_sessions
integer

Number of charge sessions (optional).

total_charging_duration
integer

Total charging duration (optional).

total_idling_duration
integer

Total idling duration (optional).

total_energy
number <float>

Total energy consumed in kWh (optional).

total_charging_fee
number <float>

Total charging fee (optional).

total_charging_fee_with_gst
number <float>

Total charging fee with GST (optional).

total_idling_fee
number <float>

Total idling fee (optional).

total_idling_fee_with_gst
number <float>

Total idling fee with GST (optional).

total_earning
number <float>

Total earnings (optional).

total_earning_with_gst
number <float>

Total earnings with GST (optional).

total_tariff
number <float>

Total tariff (optional).

total_tariff_with_gst
number <float>

Total tariff with GST (optional).

subscription_fee
number <float>

Subscription fee (optional).

subscription_fee_with_gst
number <float>

Subscription fee with GST (optional).

total_transaction_fee
number <float>

Total transaction fee (optional).

total_transaction_fee_with_gst
number <float>

Total transaction fee with GST (optional).

total_expense
number <float>

Total expense (optional).

profit
number <float>

Profit (optional).

cpo_profit_sharing_percentage
number <float>

CPO profit sharing percentage (optional).

cpo_profit_sharing
number <float>

CPO profit sharing (optional).

sp_profit_sharing_percentage
number <float>

SP profit sharing percentage (optional).

sp_profit_sharing
number <float>

SP profit sharing (optional).

Responses

Request samples

Content type
application/json
{
  • "month": 5,
  • "year": 2024,
  • "location_id": "60d0fe4f5311236168a109ca",
  • "cpo_id": "60d0fe4f5311236168a109cd",
  • "evse_id": "60d0fe4f5311236168a109cf",
  • "evse_name": "EVSE-001",
  • "charge_point_id": "60d0fe4f5311236168a109ce",
  • "charge_point_name": "Charge Point 1",
  • "location_name": "Location A",
  • "cpo_name": "CPO XYZ",
  • "cpo_email": "[email protected]",
  • "cpo_phone": "+123456789",
  • "sp_id": "60d0fe4f5311236168a109d1",
  • "sp_name": "Seeding Partner A",
  • "sp_email": "[email protected]",
  • "sp_phone": "+987654321",
  • "number_of_charge_sessions": 100,
  • "total_charging_duration": 5000,
  • "total_idling_duration": 3000,
  • "total_energy": 200.5,
  • "total_charging_fee": 100,
  • "total_charging_fee_with_gst": 107,
  • "total_idling_fee": 50,
  • "total_idling_fee_with_gst": 53.5,
  • "total_earning": 150,
  • "total_earning_with_gst": 160.5,
  • "total_tariff": 200,
  • "total_tariff_with_gst": 214,
  • "subscription_fee": 20,
  • "subscription_fee_with_gst": 21.2,
  • "total_transaction_fee": 10,
  • "total_transaction_fee_with_gst": 10.7,
  • "total_expense": 80,
  • "profit": 70,
  • "cpo_profit_sharing_percentage": 0.2,
  • "cpo_profit_sharing": 14,
  • "sp_profit_sharing_percentage": 0.1,
  • "sp_profit_sharing": 7
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

Update a performance report

Updates an existing performance report for a given type (evse or location) and report ID.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
type
required
string
Enum: "evse" "location"

The type of the report (either "evse" or "location").

id
required
string^[a-fA-F0-9]{24}$

The unique ID of the performance report (MongoDB ObjectId).

Request Body schema: application/json
required
month
integer

The month of the report (1 to 12).

year
integer

The year of the report (must be 2000 or later).

location_id
string

The location ID (MongoDB ObjectId).

cpo_id
string

The CPO ID (MongoDB ObjectId).

evse_id
string

The EVSE ID (MongoDB ObjectId).

evse_name
string

The name of the EVSE.

charge_point_id
string

The charge point ID (MongoDB ObjectId).

charge_point_name
string

The name of the charge point.

location_name
string

The name of the location.

cpo_name
string

The name of the CPO.

cpo_email
string <email>

The email of the CPO.

cpo_phone
string

The phone number of the CPO.

sp_id
string

The SP ID (MongoDB ObjectId).

sp_name
string

The name of the SP.

sp_email
string <email>

The email of the SP.

sp_phone
string

The phone number of the SP.

number_of_charge_sessions
integer

The number of charge sessions.

total_charging_duration
integer

The total charging duration in minutes.

total_idling_duration
integer

The total idling duration in minutes.

total_energy
number <float>

The total energy used in the session in watt-hours.

total_charging_fee
number <float>

The total charging fee in cents.

total_charging_fee_with_gst
number <float>

The total charging fee including GST in cents.

total_idling_fee
number <float>

The total idling fee in cents.

total_idling_fee_with_gst
number <float>

The total idling fee including GST in cents.

total_earning
number <float>

The total earnings in cents.

total_earning_with_gst
number <float>

The total earnings including GST in cents.

total_tariff
number <float>

The total tariff in cents.

total_tariff_with_gst
number <float>

The total tariff including GST in cents.

subscription_fee
number <float>

The subscription fee in cents.

subscription_fee_with_gst
number <float>

The subscription fee including GST in cents.

total_transaction_fee
number <float>

The total transaction fee in cents.

total_transaction_fee_with_gst
number <float>

The total transaction fee including GST in cents.

total_expense
number <float>

The total expenses in cents.

profit
number <float>

The profit in cents.

cpo_profit_sharing_percentage
number <float>

The CPO's profit-sharing percentage (0 to 1).

cpo_profit_sharing
number <float>

The CPO's profit-sharing amount in cents.

sp_profit_sharing_percentage
number <float>

The SP's profit-sharing percentage (0 to 1).

sp_profit_sharing
number <float>

The SP's profit-sharing amount in cents.

Responses

Request samples

Content type
application/json
{
  • "month": 12,
  • "year": 2024,
  • "location_id": "605c72ef1532071b1c13062b",
  • "cpo_id": "605c72ef1532071b1c13062c",
  • "evse_id": "605c72ef1532071b1c13062d",
  • "evse_name": "EVSE 1",
  • "charge_point_id": "605c72ef1532071b1c13062e",
  • "charge_point_name": "Charge Point 1",
  • "location_name": "Location A",
  • "cpo_name": "CPO Name",
  • "cpo_email": "[email protected]",
  • "cpo_phone": "+123456789",
  • "sp_id": "605c72ef1532071b1c13062f",
  • "sp_name": "SP Name",
  • "sp_email": "[email protected]",
  • "sp_phone": "+987654321",
  • "number_of_charge_sessions": 150,
  • "total_charging_duration": 1200,
  • "total_idling_duration": 300,
  • "total_energy": 5000,
  • "total_charging_fee": 2000,
  • "total_charging_fee_with_gst": 2200,
  • "total_idling_fee": 500,
  • "total_idling_fee_with_gst": 550,
  • "total_earning": 2500,
  • "total_earning_with_gst": 2750,
  • "total_tariff": 1000,
  • "total_tariff_with_gst": 1100,
  • "subscription_fee": 300,
  • "subscription_fee_with_gst": 330,
  • "total_transaction_fee": 100,
  • "total_transaction_fee_with_gst": 110,
  • "total_expense": 500,
  • "profit": 2000,
  • "cpo_profit_sharing_percentage": 0.1,
  • "cpo_profit_sharing": 200,
  • "sp_profit_sharing_percentage": 0.15,
  • "sp_profit_sharing": 300
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": {
    }
}

List performance reports

Returns performance reports for a given month and year, optionally filtered by admin or location. Monetary and energy values are transformed for display.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
month
required
integer [ 1 .. 12 ]
year
required
integer
admin_id
string
location_id
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Netsuite

Send customer to Netsuite

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Customer ID

Responses

Response samples

Content type
application/json
{
  • "Code": 200,
  • "Message": "Success"
}

Send invoice to Netsuite

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Invoice ID

Responses

Response samples

Content type
application/json
{
  • "invoice": { },
  • "response": {
    }
}

Reward Program

Get a list of reward programs

Retrieve a list of reward programs with optional filters and pagination.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
name
string

Filter by program name (case-insensitive, partial match).

status
boolean

Filter by status.

per_page
integer
Default: 10

Number of records per page for pagination (default is 10).

page
integer
Default: 1

Page number for pagination (default is 1).

Responses

Response samples

Content type
application/json
{}

Create a new reward program

Create a new reward program with the specified details.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
name
string

Name of the reward program.

description
string

Description of the reward program.

status
string
Enum: "active" "inactive" "pending" "ended" "expired"

Status of the reward program.

images
Array of strings <uri> <= 20 items [ items <uri > ]

List of reward program image URLs.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Get a specific reward program by ID

Retrieve details of a specific reward program by its ID.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string <uuid>

The unique identifier of the reward program.

Responses

Response samples

Content type
application/json
{}

Update a specific reward program by ID

Update the details of a specific reward program by its ID.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string <uuid>

The unique identifier of the reward program.

Request Body schema: application/json
required
name
string

Name of the reward program.

description
string

Description of the reward program.

status
string
Enum: "active" "inactive" "pending" "ended" "expired"

Status of the reward program.

images
Array of strings <uri> <= 20 items [ items <uri > ]

List of reward program image URLs.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Delete a specific reward program by ID

Delete a specific reward program by its ID.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string <uuid>

The unique identifier of the reward program.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "message": "Reward program deleted successfully."
}

Ampeco

Sync a charge point from Ampeco

Forwards a request to the charging service to sync the given Ampeco charge point into the local system.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
ampeco_chargepoint_id
required
string

Responses

Request samples

Content type
application/json
{
  • "ampeco_chargepoint_id": "12345"
}

Response samples

Content type
application/json
{
  • "ok": true
}

Audit Log

List audit logs

Proxies to the audit log service to list audit log entries. Results are scoped to the authenticated admin, and further scoped by CPO or Seeding Partner when applicable. Admin and CPO/seeding partner data is mapped onto the returned records.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
page
integer >= 1
per_page
integer >= 1
search
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

List audit logs for an EVSE

Proxies to the audit log service to list audit log entries for a specific EVSE. Results are scoped by CPO or Seeding Partner when the admin has that role.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string
query Parameters
page
integer >= 1
per_page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

List audit logs by type

Proxies to the audit log service to list audit log entries of a given type. Results are scoped by CPO or Seeding Partner when the admin has that role.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
type
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Me

Get the authenticated admin

Returns the currently authenticated admin user resolved from the request token.

Authorizations:
(AuthorizationTokenAuthorizationRole)

Responses

Response samples

Content type
application/json
{}

Merchants

List merchants

Proxies to the subscription service to list merchants. Supports pagination and filtering via query parameters.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
page
integer >= 1
per_page
integer >= 1
search
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Get a merchant by ID

Proxies to the subscription service to fetch a single merchant by its ID.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Notifications

Send a push notification to a user

Looks up a user by email via the user service and sends them a push notification with the given title and body. Optional notification_data is forwarded to the device.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
email
required
string <email>
title
required
string
body
required
string
notification_data
object

Arbitrary key/value payload delivered with the notification.

Responses

Request samples

Content type
application/json
{
  • "email": "[email protected]",
  • "title": "Your charge is complete",
  • "body": "Your vehicle has finished charging.",
  • "notification_data": { }
}

Response samples

Content type
application/json
{
  • "ok": true
}

Send a batch notification

Forwards a batch notification request to the notification service. Notifications may be sent as push notifications or emails to the provided list of recipient emails.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
emails
required
Array of strings <email> [ items <email > ]
title
required
string
body
required
string
notification_type
required
string
Enum: "push-notification" "email"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "ok": true
}

Payments

Make a payment on behalf of a user

Forwards a payment request to the payment service for the given user, amount and payment method (wallet, stripe or card).

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
user_id
required
string
amount
required
number
payment_method
required
string
Enum: "wallet" "stripe" "card"
payment_card_id
string

Required when paying with a saved card.

type
string

Payment type/category.

description
string
additional_data
object

Extra metadata forwarded to the payment service.

Responses

Request samples

Content type
application/json
{
  • "user_id": "60f7a9b8c1234567890abcde",
  • "amount": 25.5,
  • "payment_method": "wallet",
  • "payment_card_id": "string",
  • "type": "string",
  • "description": "string",
  • "additional_data": { }
}

Response samples

Content type
application/json
{
  • "ok": true
}

Refund a payment

Refunds the given amount for a transaction via the payment service. The amount is converted to cents before being forwarded.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
transaction_id
required
string
amount
required
number
description
string

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "60f7a9b8c1234567890abcde",
  • "amount": 10,
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "ok": true
}

Point Histories

Get points statistics for a user

Proxies to the loyalty service to fetch points statistics for the given user.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
user_id
required
string

Valid Mongo ID of the user.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Reports

Auto-generate monthly reports

Auto-generates monthly reports for the given month and year, recording the requesting admin as the creator. Monetary values in the response are converted to dollars.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
year
required
integer
month
required
integer
created_from
string
Default: "admin-auto-generate"

Responses

Request samples

Content type
application/json
{
  • "year": 0,
  • "month": 0,
  • "created_from": "admin-auto-generate"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Generate all monthly reports for a period

Triggers generation of all reports for the given year and month by proxying to the report service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
year
required
string
month
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Attach Google Drive report links

Registers Google Drive download links for generated reports. Only Superadmins may perform this action.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
required
Array of objects non-empty

Responses

Request samples

Content type
application/json
{
  • "google_link_list": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true
}

List monthly reports

Returns a paginated list of published monthly reports. Seeding Partner and CPO roles are scoped to their own records; Superadmins see all statuses.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
page
integer
Default: 1
per_page
integer
Default: 10

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Create a monthly report

Creates a new monthly report for an admin. Only Superadmins may perform this action. The server resolves the admin's locations, charge points and EVSEs before persisting the report.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
admin_id
required
string

Admin Mongo ID

total_earning
required
number
total_earning_with_gst
number
total_expense
required
number
total_expense_with_gst
number
total_transaction_fee
required
number
total_transaction_fee_with_gst
number
profit
required
number
payout_with_gst
number
required
object
file_url
string

Responses

Request samples

Content type
application/json
{
  • "admin_id": "string",
  • "total_earning": 0,
  • "total_earning_with_gst": 0,
  • "total_expense": 0,
  • "total_expense_with_gst": 0,
  • "total_transaction_fee": 0,
  • "total_transaction_fee_with_gst": 0,
  • "profit": 0,
  • "payout_with_gst": 0,
  • "period": {
    },
  • "file_url": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Get monthly report dashboard totals

Returns a single aggregated dashboard metric for monthly reports. Superadmins see all admins; other roles are scoped to their own admin id. Monetary values are converted to dollars.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
type
required
string
Enum: "total_earning" "total_expense" "total_transaction_fee" "total_electricity_reimbursement" "total_payout"

Metric to return.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Publish monthly reports

Publishes the monthly reports for the given month and year.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
month
required
integer [ 1 .. 12 ]
year
required
integer

Responses

Request samples

Content type
application/json
{
  • "month": 1,
  • "year": 0
}

Response samples

Content type
application/json
{
  • "ok": true
}

Get a monthly report

Returns a single monthly report by its ID.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Update a monthly report

Updates the financial figures of an existing monthly report by ID.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string
Request Body schema: application/json
required
total_earning
required
number
total_expense
required
number
profit
required
number
total_transaction_fee
required
number
total_payout
number
total_electricity_reimbursement
number

Responses

Request samples

Content type
application/json
{
  • "total_earning": 0,
  • "total_expense": 0,
  • "profit": 0,
  • "total_transaction_fee": 0,
  • "total_payout": 0,
  • "total_electricity_reimbursement": 0
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Delete a monthly report

Deletes a monthly report by its ID.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Reward Banners

List reward banners

Returns a paginated list of reward banners, proxied from the Loyalty service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
title
string
page
integer >= 1
per_page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Create a reward banner

Creates a new reward banner via the Loyalty service and records an admin log entry.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
title
required
string
subtitle
string or null
detail_url
required
string
image
required
string <uri>

Banner image URL.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "subtitle": "string",
  • "detail_url": "string",
  • "image": "http://example.com"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Get a reward banner

Returns a single reward banner by ID, proxied from the Loyalty service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Update a reward banner

Updates an existing reward banner via the Loyalty service and records an admin log entry.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string
Request Body schema: application/json
required
title
required
string
subtitle
string or null
detail_url
required
string
image
required
string <uri>

Banner image URL.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "subtitle": "string",
  • "detail_url": "string",
  • "image": "http://example.com"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Delete a reward banner

Deletes a reward banner via the Loyalty service and records an admin log entry.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Reward Categories

List reward categories

Returns a paginated list of reward categories, proxied from the Loyalty service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
name
string
code
string
ids
string
page
integer >= 1
per_page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Create a reward category

Creates a new reward category via the Loyalty service after checking the code is unique, and records an admin log entry.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
code
required
string
name
required
string
description
string

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { },
  • "msg": "string"
}

Get a reward category

Returns a single reward category by ID, proxied from the Loyalty service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Update a reward category

Updates an existing reward category via the Loyalty service and records an admin log entry.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string
Request Body schema: application/json
required
name
required
string
code
required
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "code": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Delete a reward category

Deletes a reward category via the Loyalty service and records an admin log entry.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Reward Programs

Fetch reward programs by IDs

Returns the reward programs matching the supplied list of IDs by proxying the request to the Loyalty service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
ids
required
Array of strings

List of reward program MongoIDs.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Recalculate reward program statistics

Triggers a recalculation of the aggregated statistics for the given reward program by proxying the request to the Loyalty service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string
Request Body schema: application/json
optional
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Reward Types

List reward types

Returns a paginated list of reward types, proxied from the Loyalty service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
reward_program_id
string
reward_program_name
string
reward_type_code
string
reward_type_name
string
code
string
ids
string
page
integer >= 1
per_page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Create a reward type

Creates a new reward type via the Loyalty service after checking the code is unique, and records an admin log entry.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
code
required
string
name
required
string
description
string

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { },
  • "msg": "string"
}

Get a reward type

Returns a single reward type by ID, proxied from the Loyalty service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Reward Vendors

List reward vendors

Returns a paginated list of reward vendors, proxied from the Loyalty service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
name
string
code
string
ids
string
page
integer >= 1
per_page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Create a reward vendor

Creates a new reward vendor via the Loyalty service after checking the code is unique, and records an admin log entry.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
code
required
string
name
required
string
description
string

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { },
  • "msg": "string"
}

Get a reward vendor

Returns a single reward vendor by ID, proxied from the Loyalty service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Update a reward vendor

Updates an existing reward vendor via the Loyalty service and records an admin log entry.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string
Request Body schema: application/json
required
name
required
string
code
required
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "code": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Delete a reward vendor

Deletes a reward vendor via the Loyalty service and records an admin log entry.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Rewards

List rewards

Returns a paginated list of rewards from the Loyalty service, filterable by reward program, reward type, user, code, and status.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
reward_program_id
string
reward_program_name
string
reward_type_code
string
reward_type_name
string
user_id
string
code
string
status
string
Enum: "new" "redeemed" "expired" "used"
ids
string
page
integer >= 1
per_page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Generate a batch of rewards

Generates a batch of reward codes under a reward program via the Loyalty service and records an admin activity log.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
reward_program_id
required
string
value
required
number
reward_type_code
required
string
expiry_datetime
required
string <date-time>
quantity_codes
required
integer >= 1

Responses

Request samples

Content type
application/json
{
  • "reward_program_id": "string",
  • "value": 0,
  • "reward_type_code": "string",
  • "expiry_datetime": "2019-08-24T14:15:22Z",
  • "quantity_codes": 1
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Import rewards from Excel

Uploads an Excel file of rewards and imports them under the given reward program via the Loyalty service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: multipart/form-data
required
file
required
string <binary>

Excel file to import

reward_program_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "Rewards imported successfully",
  • "data": { }
}

Backfill user info on rewards

Maintenance job that iterates over rewards missing denormalized user fields and backfills user_name, user_email, and user_phone from the users collection in batches.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
limit
integer
Default: 1000

Batch size per iteration

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "Processed all rewards successfully"
}

Get reward details

Returns details for a single reward by ID from the Loyalty service.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Assign a reward to a user

Assigns the specified reward to a user via the Loyalty service, attaching the acting admin's identity, and records an admin activity log.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string
Request Body schema: application/json
required
user_id
required
string

ID of the user to assign the reward to

Responses

Request samples

Content type
application/json
{
  • "user_id": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Mark a reward as used

Looks up the reward and its associated user, then marks the reward as used via the Loyalty service and records an admin activity log.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "msg": "Reward marked as used successfully.",
  • "data": { }
}

Assign a reward to a charge session

Assigns the specified reward to a charge session via the Loyalty service, attaching the acting admin's identity, and records an admin activity log.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
reward_id
required
string
Request Body schema: application/json
required
charge_session_id
required
string

Responses

Request samples

Content type
application/json
{
  • "charge_session_id": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Subscription Plans

List subscription plans

Returns a paginated list of subscription plans, proxied from the subscription service. Supports filtering by keyword, merchant and status.

Authorizations:
(AuthorizationTokenAuthorizationRole)
query Parameters
keyword
string
merchant_id
string

Filter by merchant ID (Mongo ObjectId).

merchant_code
string

Merchant code (starts with "M").

status
string
Enum: "active" "inactive" "deleted"
deleteAt
string
page
integer >= 1
per_page
integer >= 1

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Create a subscription plan

Creates a new subscription plan. The code must be unique. Records an admin log entry on success.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
code
required
string

Unique plan code

name
required
string
description
required
string
status
required
string
Enum: "active" "inactive" "draft"
quotation
required
object
merchant_id
string
expiration_type
string
Enum: "month" "year"
expiration_duration
number
payment_status
string
prices
Array of objects

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "name": "string",
  • "description": "string",
  • "status": "active",
  • "quotation": { },
  • "merchant_id": "string",
  • "expiration_type": "month",
  • "expiration_duration": 0,
  • "payment_status": "string",
  • "prices": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Export subscription plans to Excel

Exports the filtered subscription plan list as an .xlsx file.

Authorizations:
(AuthorizationTokenAuthorizationRole)

Responses

Response samples

Content type
application/json
{
  • "ok": false,
  • "msg": "Something went wrong, please contact CS for supporting."
}

Generate plan activation codes

Generates a batch of activation codes for a subscription plan and merchant. Records an admin log entry on success.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
subscription_plan_id
string
subscription_plan_name
string
subscription_plan_code
string
merchant_id
required
string
number_of_codes
required
integer
prefix
string
expired_date
required
string <date>
plan_price
object
quotation
object

Responses

Request samples

Content type
application/json
{
  • "subscription_plan_id": "string",
  • "subscription_plan_name": "string",
  • "subscription_plan_code": "string",
  • "merchant_id": "string",
  • "number_of_codes": 0,
  • "prefix": "string",
  • "expired_date": "2019-08-24",
  • "plan_price": { },
  • "quotation": { }
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Subscribe a user to a plan

Subscribes a user to a subscription plan at a given price. Records an admin log entry on success.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
subscription_plan_id
required
string

Mongo ObjectId of the plan

user_id
required
string

Mongo ObjectId of the user

object
active_date
string <date>

yyyy-mm-dd

Responses

Request samples

Content type
application/json
{
  • "subscription_plan_id": "string",
  • "user_id": "string",
  • "plan_price": {
    },
  • "active_date": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Get a subscription plan

Returns the details of a single subscription plan.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
subscription_plan_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Update a subscription plan

Updates an existing subscription plan. If code is supplied it must remain unique. Records an admin log entry capturing old and new state.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
subscription_plan_id
required
string
Request Body schema: application/json
code
string
description
string
status
string
Enum: "active" "inactive" "draft"
quotation
object
merchant_id
string
expiration_type
string
Enum: "month" "year"
expiration_duration
number
prices
Array of objects
payment_status
string

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "description": "string",
  • "status": "active",
  • "quotation": { },
  • "merchant_id": "string",
  • "expiration_type": "month",
  • "expiration_duration": 0,
  • "prices": [
    ],
  • "payment_status": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": { }
}

Delete a subscription plan

Deletes the given subscription plan via the subscription service and records an admin log entry.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
subscription_plan_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Tokenized Card

List a user's tokenized cards

Verifies the user exists via the user service, then proxies to the payment service to list the tokenized (saved) cards for that user.

Authorizations:
(AuthorizationTokenAuthorizationRole)
path Parameters
user_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Reward Type

Get multiple reward types by IDs

Retrieve multiple reward types in a single request by passing an array of their IDs.

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
ids
required
Array of strings <objectId> [ items <objectId > ]

Array of reward type IDs (MongoDB ObjectIds) to fetch.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}

Reward

Get multiple rewards by IDs

Retrieve multiple rewards in a single request by passing an array of their IDs. Note: the response returns a projected subset of each reward (_id, name, value, value_type, status).

Authorizations:
(AuthorizationTokenAuthorizationRole)
Request Body schema: application/json
required
ids
required
Array of strings <objectId> [ items <objectId > ]

Array of reward IDs (MongoDB ObjectIds) to fetch.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "data": [
    ]
}