Client plans management

Methods in this section are related to Forguard and Tags solution.

The specificity of Forguard and Tags accounts lies in assigning a client plan upon creation, wherein service providers (dealers) determine the available account limits and control specific application features/modules when creating a client plan.

The client plan, in turn, is built upon partner plans offered by the GPS-Trace platform.

Client plans consist of two sections:

Quotas
Modules

Quotas include limits on unit quantity per account, geofence quantity, and maximum data storage limit.

Forguard quotas:

"quotas": {
  "unit": number,
  "geofence": number,
  "unit_storage": number
}

Tags quotas:

"quotas": {
  "sensor": number,
  "gateway": number,
  "asset": number,
  "geofence": number,
  "unit_storage": number
}

Modules are specific features or functionalities within the Forguard and Tags applications that service providers can choose to enable or disable in a client plan for a client account at their discretion.

Available modules in Forguard:

service_mode - Activates Service Mode option
tools - Activates Toolbox and SetBox
notifications - Activates basic notifications in the app, providing access to view and configure notifications (Simple and Customizable)
unit_event - Activates the Event option
geofence - Activates Geofences
timeline - Activates Timeline
sharing - Activates the Sharing option
command - Activates the Commands Panel
google_maps - Allows the use of Google Maps
statistics - Activates Statistics
extended_notification - Activates sending methods such as by email, Webhook, and Telegram. Enables Own notifications working by parameters.
maintenance - Activates Maintenance tab with mileage and engine hours counters
account - default module
unit - default module

Available modules in Tags:

geofence - Activates Geofences
report - Activates Reports
building - Activates Buildings(layers)
label - Activates Labels (default module)
timeline - Activates Timeline (default module)
unit_event - Activates Events (default module)
account - default module
unit - default module

Service providers use a partner plan to create a client plan, adjusting the limits based on the partner plan.

For instance, if a partner plan has a 10 units limit per account, the service provider can set a lower value but not exceed 10 units in the client plan.

Scheme for creating a Forguard account:

Forguard Account (1)

Create client plan

This API endpoint allows for the creation of a client plan, which is used in the process of creating Forguard or Tags accounts.

POST /provider/client-plans

The mandatory fields for this request:

"managed_plan_id": "string" - The identifier of the partner plan on which the client plan is based. The list of partner plans can be obtained using the GET /billing/managed-plans method.
"app_id": "string" - The ID of the application to which this tariff belongs.
- Forguard - b901da51-ce00-4af2-b978-8d0fca8ae1ea
- Tags - de7f31b0-c485-4bf3-b48b-994bd333e7f2
"name": "string" - Client plan name
"quotas": {} - This is an object containing information about the quotas associated with the creation of a client plan. It includes three fields:
- "unit": number - Represents the limit for the number of units available in the client plan.
- "geofence": number - Specifies the limit for the number of geofences allowed in the client plan.
- "unit_storage": number - Indicates the limit for the unit storage capacity in the client plan. The count should range between 10240 and 204800, depending on the partner plan limit. Step: 10240. Each step represents 10 MB.
"modules": [] - This is an array listing the modules that will be available (enabled) in the client plan.

Available modules in Forguard:

service_mode - Activates Service Mode option
tools - Activates Toolbox and SetBox
notifications - Activates basic notifications in the app, providing access to view and configure notifications (Simple and Customizable)
unit_event - Activates the Event option
geofence - Activates Geofences
timeline - Activates Timeline
sharing - Activates the Sharing option
command - Activates the Commands Panel
google_maps - Allows the use of Google Maps
statistics - Activates Statistics
extended_notification - Activates sending methods such as by email, Webhook, and Telegram. Enables Own notifications working by parameters.
maintenance - Activates Maintenance tab with mileage and engine hours counters

Available modules in Tags:

geofence - Activates Geofences
report - Activates Reports
label - Activates Labels (default module)
building - Activates Buildings(layers)

Request body example:

curl -X 'POST' \
  'https://api.gps-trace.com/provider/client-plans' \
  -H 'accept: application/json' \
  -H 'X-AccessToken: ' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Client Plan",
  "description": "Client plan description",
  "quotas": {
    "unit": 30,
    "geofence": 50,
    "unit_storage": 204800},
  "modules": [
    "command",
    "google_maps",
    "geofence",
    "statistics",
    "tools",
    "extended_notification",
    "unit_event",
    "sharing",
    "timeline",
    "notification",
    "maintenance",
    "service_mode"
  ],
  "managed_plan_id": "string",
  "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea"
}'

Modules 'account', 'unit', and 'fuel' are always enabled by default in Forguard accounts. They can only be seen in the response to the request.

Modules 'account', 'unit', 'label', 'timeline' and 'unit_event' are always enabled by default in Tags accounts.

201 Response example:

{
  "quotas": {
    "unit": 30,
    "geofence": 50,
    "unit_storage": 204800
  },
  "creator_id": number,
  "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
  "updated_at": number,
  "description": "Client plan description",
  "managed_plan_id": "string",
  "modules": [
    "notification",
    "command",
    "account",
    "geofence",
    "service_mode",
    "sharing",
    "unit_event",
    "timeline",
    "statistics",
    "extended_notification",
    "maintenance",
    "tools",
    "unit",
    "google_maps"
  ],
  "client_payment_lifecycle": null,
  "name": "Client Plan",
  "created_at": number,
  "id": "string"
}

Set Billing automation

This API endpoint allows for the set client billing automation for a client plan, which is used in the process of managed clients payments.

The client billing automation parameters can be obtained using the GET /billing/managed-plans

PATCH /provider/client-plans/{client plan id}/payment-lifecycle

The mandatory fields for this request:

payment_notify_offset: number - Notification about client payment before due date in days (minimum: 0; maximum: 10)
block_offset: number - Number of days after which the client plan will be blocked if the payment is not made after the due date (minimum: 0; maximum: 10)
payment_period: number - Client's payment period in months (minimum: 1; maximum: 120)

Request body example:

curl -X 'POST' \
  'https://api.gps-trace.com/provider/client-plans/xxxxxxx/payment-lifecycle' \
  -H 'accept: application/json' \
  -H 'X-AccessToken: ' \
  -H 'Content-Type: application/json' \
  -d '{
  "payment_notify_offset": 5,
  "block_offset": 5,
  "payment_period": null
}

201 Response example:

{
  "quotas": {
    "unit": 30,
    "geofence": 50,
    "unit_storage": 204800
  },
  "creator_id": number,
  "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
  "updated_at": number,
  "description": "Client plan description",
  "managed_plan_id": "string",
  "modules": [
    "notification",
    "command",
    "account",
    "geofence",
    "service_mode",
    "sharing",
    "unit_event",
    "timeline",
    "statistics",
    "extended_notification",
    "maintenance",
    "tools",
    "unit",
    "google_maps"
  ],
  "name": "Client Plan",
  "created_at": number,
  "id": "string",
  "client_payment_lifecycle": {
    "payment_period": null,
    "payment_notify_offset": 5,
    "block_offset": 5
  }
}

Get list of client plans

This API endpoint allows you to obtain a list of created client plans.

GET /provider/client-plans

200 Response example:

[
  {
    "id": "string",
    "quotas": {
      "unit": 20,
      "geofence": 0,
      "unit_storage": 10240
    },
    "name": "Test",
    "creator_id": number,
    "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
    "managed_plan_id": "string",
    "updated_at": number,
    "description": null,
    "created_at": number,
    "modules": [
      "service_mode",
      "account",
      "unit"
    ],
    "client_payment_lifecycle": {
      "payment_period": null,
      "payment_notify_offset": 5,
      "block_offset": 5
    }
  },
  {
    "id": "string",
    "quotas": {
      "unit": 10,
      "unit_storage": 102400,
      "geofence": 50
    },
    "name": "Test2",
    "creator_id": number,
    "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
    "managed_plan_id": "string",
    "updated_at": number,
    "description": null,
    "created_at": number,
    "modules": [
      "tools",
      "unit_event",
      "command",
      "google_maps",
      "statistics",
      "unit",
      "maintenance",
      "service_mode",
      "notification",
      "account",
      "extended_notification",
      "sharing",
      "timeline",
      "fuel",
      "geofence"
    ],
    "client_payment_lifecycle": null
  }
]

The response includes information about client plans available, with each plan represented by an object containing the following fields:

id: string - unique identifier for the client plan.
name: string - name of the client plan.
creator_id: number - ID of the provider account who created the client plan.
app_id: string - ID of the application associated with this client plan.
managed_plan_id: string - ID of the partner plan upon which this client plan is based.
updated_at: number - timestamp indicating when the client plan was updated.
description: string - description of the client plan.
created_at: number - timestamp indicating when the client plan was created.
quotas - this is an object containing information about the quotas associated with the creation of a client plan. It includes three fields:
- unit: number - represents the limit for the number of units available in the client plan.
- geofence: number - specifies the limit for the number of geofences allowed in the client plan.
- unit_storage: number - indicates the limit for the unit storage capacity in the client plan. The count should range between 10240 and 204800, depending on the partner plan limit. Step: 10240. Each step represents 10 MB.
modules: [] - this is an array listing the modules that will be available (enabled) in the client plan.

Available modules in Forguard:

service_mode - Activates Service Mode option
tools - Activates Toolbox and SetBox
notifications - Activates basic notifications in the app, providing access to view and configure notifications (Simple and Customizable)
unit_event - Activates the Event option
geofence - Activates Geofences
timeline - Activates Timeline
sharing - Activates the Sharing option
command - Activates the Commands Panel
google_maps - Allows the use of Google Maps
statistics - Activates Statistics
extended_notification - Activates sending methods such as by email, Webhook, and Telegram. Enables Own notifications working by parameters.
maintenance - Activates Maintenance tab with mileage and engine hours counters
account - default module
unit - default module

Available modules in Tags:

geofence - Activates Geofences
report - Activates Reports
building - Activates Buildings(layers)
label - Activates Labels (default module)
timeline - Activates Timeline (default module)
unit_event - Activates Events (default module)
account - default module
unit - default module

creator_id: number - provider account ID
client_payment_lifecycle - Billing automation settings
- payment_notify_offset: number - Notification about client payment before due date in days (minimum: 0; maximum: 10)
- block_offset: number - Number of days after which the client plan will be blocked if the payment is not made after the due date (minimum: 0; maximum: 10)
- payment_period: number - Client's payment period in months (minimum: 1; maximum: 120)

Get client plan by ID

This API endpoint allows you to get information about a specific client plan by its ID.

GET /provider/client-plans/{id}

id: string - unique identifier for the client plan.

200 Response example:

{
  "id": "string",
  "quotas": {
    "unit": 20,
    "geofence": 0,
    "unit_storage": 10240
  },
  "name": "Test",
  "creator_id": number,
  "app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
  "managed_plan_id": "string",
  "updated_at": number,
  "description": null,
  "created_at": number,
  "modules": [
    "service_mode",
    "account",
    "unit"
  ],
  "client_payment_lifecycle": {
    "payment_period": null,
    "payment_notify_offset": 5,
    "block_offset": 5
  }
}

Delete client plan

This API endpoint allows you to delete client plan by its ID.

DELETE /provider/client-plans/{id}

"id": "string" - The unique identifier for the client plan.

Upon successful deletion, a response with status code 200 will be returned, along with the ID of the client plan that was removed.

200 Response example:

"string"

Get modules

This endpoint allows to retrieve information about the modules used in creating client plans.

GET /provider/client-plans/modules

Creating Forguard account requires assigning a client plan to it. Client plans are made based on partner plans provided by the GPS-Trace platform.

Partner plans consist of two main parts:

Limits - include unit max quantity per account, geofence quantity, and data storage limit.

Example of limits:

"limits": {
  "geofence": {
    "default": 35,
    "max": 70,
    "min": 0,
    "step": 1
  },
  "unit": {
    "default": 35,
    "max": 70,
    "min": 1,
    "step": 1
  },
  "unit_storage": {
    "default": 102400,
    "max": 204800,
    "min": 10240,
    "step": 10240
  }
}

Modules - specific features or functionalities within the Forguard and Tags applications that service providers can choose to enable or disable in a client plan for a client account at their discretion

Available modules in Forguard:

service_mode - Activates Service Mode option
tools - Activates Toolbox and SetBox
notifications - Activates basic notifications in the app, providing access to view and configure notifications (Simple and Customizable)
unit_event - Activates the Event option
geofence - Activates Geofences
timeline - Activates Timeline
sharing - Activates the Sharing option
command - Activates the Commands Panel
google_maps - Allows the use of Google Maps
statistics - Activates Statistics
extended_notification - Activates sending methods such as by email, Webhook, and Telegram. Enables Own notifications working by parameters.
maintenance - Activates Maintenance tab with mileage and engine hours counters
account - default module
unit - default module

Available modules in Tags:

geofence - Activates Geofences
report - Activates Reports
building - Activates Buildings(layers)
label - Activates Labels (default module)
timeline - Activates Timeline (default module)
unit_event - Activates Events (default module)
account - default module
unit - default module

creator_id: number - provider account ID
client_payment_lifecycle - Billing automation settings

Client plans based on partner plans and include specific quotas and modules. Quotas for geofences, units, and data storage volume are set during client plan creation, within the limits of the partner plan. Service providers can activate or deactivate modules available in the partner plan.

For instance, a service provider might select a partner plan allowing 70 units, create a client plan based on it, set a 50-unit limit, and apply this plan to a Forguard account for the client to track up to 50 units.

Modules 'account', 'unit', and 'fuel' are always enabled by default in Forguard accounts. They can only be seen in the response to the request. Modules 'account', 'unit', 'label', 'timeline' and 'unit_event' are always enabled by default in Tags accounts.

200 Response example:

[
  {
    "default_included": false,
    "name": "tools",
    "hidden": false,
    "required": false,
    "depended_on": [],
    "default_access": 15,
    "access_list": [ 15 ]
  },
  {
    "default_included": false,
    "name": "service_mode",
    "hidden": false,
    "required": false,
    "depended_on": [],
    "default_access": 15,
    "access_list": [ 15 ]
  },
  ...
]