Billing
The 'Billing' section of the API provides partners an information regarding financial aspects related to their accounts within GPS-Trace platform.
This section exclusively consists of methods dedicated to retrieving various types of data, such as subscription details, partner plans, service fees and invoices.
Partners can use these methods to fetch relevant information about subscription plans, and billing-related activities, enabling them to make informed decisions and manage their accounts effectively.
Get subscriptions
This endpoint allows you to retrieve data about subscriptions applicable to a specific application.
Premium subscriptions are currently applicable to Ruhavik application. Therefore, if you request subscriptions for other applications, the response will contain default data about the free subscription.
GET /billing/plans/{app_id}
- app_id: ”string” - The ID of the application for which you want to retrieve information about all possible subscriptions.
Request example:
curl -X 'GET' \
'https://api.gps-trace.com/billing/plans/5a5ca87f-7cbe-4540-ab5d-77bf4bf69884' \
-H 'accept: */*' \
-H 'X-AccessToken: <your token>'
200 Response example:
{
"data": {
"free": {
"name": "free",
"subscriptions": [
"free"
],
"platforms": [
"google",
"web",
"apple",
"ios"
],
"subscr_types": [
"custom",
"google",
"ios-appstore",
"paypal",
"stripe",
"td-paypal",
"td-stripe",
"space"
],
"data": {
"user": 1,
"unit": 1,
"geofence": 2,
"calculator": 200,
"unit_notify_settings": null,
"triggers": 0,
"unit_storage": 10,
"config_send_notifications": false
}
},
"basic": {
"name": "basic",
"subscriptions": [
"basic.monthly",
"basic.yearly"
],
"platforms": [
"web",
"apple",
"google"
],
"subscr_types": [
"custom",
"google",
"ios-appstore",
"paypal",
"stripe"
],
"data": {
"user": 1,
"unit": 1,
"geofence": 15,
"calculator": 200,
"unit_notify_settings": null,
"triggers": 1,
"unit_storage": 100,
"config_send_notifications": true
}...
The response to the request returns an array of objects, where each object describes a subscription type applicable to the chosen application.
The provided example response showcases the first two objects from the entire array.
- name - name of the subscription.
- platforms - platforms through which you can purchase a subscription:
- google - Google Play Store
- web - Website
- apple - Apple App Store
- ios - Apple App Store for old Ruhavik accounts (deprecated)
- subscr_types - types of subscriptions:
- custom - custom subscription assigned by the GPS-Trace platform
- google - Google Play Store subscription
- ios-appstore - Apple App Store subscription
- paypal - PayPal subscription
- stripe - Stripe subscription
- td-paypal - subscription purchased by the partner for the client's account through the Partner Panel using PayPal
- td-stripe - subscription purchased by the partner for the client's account through the Partner Panel using Stripe
- space - promo subscription from GPS Trace valid for a month after the activation of the Ruhavik account created through the Partner Panel
Partner plans
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.
"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
}
}
-
- Default: In the context of creating a client plan in the Partner Panel (PP), the "default" value represents the initial or default quantity displayed on the scale of units, geofences, and storage.
- Max (Maximum): This indicates the highest or maximum possible value that can be assigned to a parameter. It sets an upper limit beyond which the parameter cannot be increased.
- Min (Minimum): This denotes the lowest or minimum possible value that can be assigned to a parameter. It sets a lower limit below which the parameter cannot be decreased.
- Step: This refers to the increment or decrement value used when adjusting the parameter. It represents the smallest unit by which the parameter can be increased or decreased.
- Modules - specific features or functionalities within the Forguard application that partners can choose to enable or disable in a client plan for a client account at their discretion. Currently, the following modules are available:
-
- service_mode - Activates Service Mode option in the app
- tools - Activates Toolbox and SetBox in the app
- notifications - Activates basic notifications in the app, providing access to view and configure notifications (Simple and Customizable)
- unit_event - Activates the Event option in the app
- geofence - Activates Geofences tab in the application
- timeline - Activates Timeline tab in the application
- sharing - Activates the Sharing option in the app
- command - Activates the Commands Panel in the app
- google_maps - Allows the use of Google Maps in the app
- statistics - Activates Statistics tab in the app
- 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.
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. Partners can activate or deactivate modules available in the partner plan.
For example, a partner might select a partner plan allowing 10 units, create a client plan based on it, set 8-unit limit, and apply this plan to a Forguard account for the client to track up to 8 units
Scheme for creating a Forguard account:
Get data about partner plans
This endpoint allows you to retrieve data about all partner plans.
GET /billing/managed-plans/{app_id}
- app_id: ”string” - The ID of the application for which you want to retrieve information about all possible partner plans.
Request example:
curl -X 'GET' \
'https://api.gps-trace.com/billing/managed-plans/b901da51-ce00-4af2-b978-8d0fca8ae1ea' \
-H 'accept: application/json' \
-H 'X-AccessToken: <your token>'
Body response example:
{
"data": [
{
"id": "68b840a975a34140831f4b0d7f3a4261",
"name": "Advanced 2024",
"status": "active",
"description": "",
"price": number,
"currency": "eur",
"period": "monthly",
"features": {
"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": [
"account",
"unit",
"fuel",
"service_mode",
"tools",
"notification",
"unit_event",
"geofence",
"timeline",
"sharing",
"command",
"statistics",
"maintenance",
"extended_notification",
"google_maps"
]
},
"data": {
"time_begin": number
},
"type": "managed"
},
...
]
}
- id: unique identifier for the partner plan.
- name: name of the partner plan.
- status: current status of the plan (active, archived, new, expired, deprecated ).
- description: description of the partner plan.
- price: price of the plan.
- currency: currency in which the price is expressed.
- period: billing period.
- features: an object containing details about the features included in the plan.
- geofence: limits related to geofencing.
- default: default value for geofence limit.
- max: maximum allowed value for geofence limit.
- min: minimum allowed value for geofence limit.
- step: incremental step for adjusting geofence limit.
- unit: limits related to units.
- default: default value for unit limit.
- max: maximum allowed value for unit limit.
- min: minimum allowed value for unit limit.
- step: incremental step for adjusting unit limit.
- unit_storage: limits related to unit storage.
- default: default value for unit storage limit.
- max: maximum allowed value for unit storage limit.
- min: minimum allowed value for unit storage limit.
- step: incremental step for adjusting unit storage limit.
- limits: an object specifying the limit:.
- modules: an array of modules included in the plan
- data: additional data related to the plan.
- time_begin: start time of the partner plan
- type: type of plan (managed, trial).
Get service fee
This endpoint allows you to retrieve information about the service fee charged monthly for utilizing the full functionality of Forguard.
GET /billing/service-plans/{app_id}
- app_id: ”string” - The ID of the application for which you want to retrieve information about all possible partner plans.
Request example:
curl -X 'GET' \ 'https://api.gps-trace.com/billing/service-plans/b901da51-ce00-4af2-b978-8d0fca8ae1ea' \
-H 'accept: application/json' \
-H 'X-AccessToken: <your token>'
Body response example:
{
"data": [
{
"id": "string",
"name": "Service fee",
"status": "active",
"description": "",
"price": number,
"currency": "eur",
"period": "monthly",
"features": {},
"data": {
"time_begin": number,
"time_end": number
}
},
...
]
}
- data: array containing information about service plans.
- id: unique identifier for the service plan.
- name: name or title of the service plan.
- status: current status of the plan (active, expired).
- description: any additional descriptive information about the plan.
- price: price of the service plan.
- currency: currency in which the price is expressed.
- period: billing period.
- features: specific features included in the service plan.
- data: additional data related to the service plan.
- time_begin: start time of the service plan.
- time_end: end time or expiration time of the service plan.
Get latest invoice data
This endpoint allows retrieving information about the latest invoice of the partner.
GET /billing/stripe-invoice/{app_id}
- app_id: ”string” - The ID of the application for which you want to retrieve information about the latest invoice.
Request example:
curl -X 'GET' \ 'https://api.gps-trace.com/billing/stripe-invoice/b901da51-ce00-4af2-b978-8d0fca8ae1ea' \
-H 'accept: application/json' \
-H 'X-AccessToken: <your token>'
Body response example:
{
"data": {
"id": "string",
"status": "open"
}
}
- id: stripe invoice ID
- status: invoice status
Get customer portal data
This method allows you to retrieve data about the customer portal.
GET /billing/customer-portal/{app_id}
- app_id: ”string” - The ID of the application for which you want to retrieve information about the customer portal.
Example of curl:
curl -X 'GET' \
'https://api.gps-trace.com/billing/customer-portal/b901da51-ce00-4af2-b978-8d0fca8ae1ea' \
-H 'accept: application/json' \
-H 'X-AccessToken: <your token>'
Example of success response:
{
"data": {
"id": "string",
"object": "billing_portal.session",
"configuration": "string",
"created": number,
"customer": "string",
"flow": null,
"livemode": false,
"locale": null,
"return_url": "https://partner.gps-trace.com/billing/forguard/billing/reports",
"url": "https://billing.stripe.com/p/session/w2sXXXXXXXXXXXX2T54w"
}
}
- id - unique identifier
- object - string representing the object’s type. Objects of the same type share the same value.
- configuration - configuration used by this session, describing the features available
- customer - ID of the customer for this session
- livemode - has the value true if the object exists in live mode or the value false if the object exists in test mode
- locale - the IETF language tag of the locale Customer Portal is displayed in. If blank or auto, the customer’s preferred_locales or browser’s locale is used.
- return_url - the URL to redirect your customer back to after they authenticate or cancel their payment on the payment method’s app or site. To redirect to a mobile application, you can alternatively supply an application URI scheme. This parameter can only be used with confirm=true
- url - short-lived URL of the session that gives customers access to the customer portal.