Dealer Billing

The Dealer (Service Provider) Billing section of the API provides service providers information regarding financial aspects related to their accounts within the 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.

Service providers 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: '

200 Response example:

{
  "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 service provider for the client's account through the GPS-Trace Console using PayPal
- td-stripe - subscription purchased by the service provider for the client's account through the GPS-Trace Console using Stripe
- space - promo subscription from GPS Trace valid for a month after the activation of the Ruhavik account created through the GPS-Trace Console

Partner plans

Creating a Forguard or Tags 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.
- Default: In the context of creating a client plan in the GPS-Trace Console, 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 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

"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
  }
}

Client Plans based on partner plans 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 example, a service provider might select a partner plan allowing 10 units, create a client plan based on it, set an 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:

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: '

Body response example:

[
  {
    "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.
- limits: an object specifying the limits:
  - 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.
- 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 latest invoice data

This endpoint allows retrieving information about the latest invoice of the service provider.

GET /billing/stripe-invoice

Request example:

curl -X 'GET' \
'https://api.gps-trace.com/billing/stripe-invoice' \
-H 'accept: application/json' \
-H 'X-AccessToken: '

Body response example:

{
  "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

Example of curl:

curl -X 'GET' \
'https://api.gps-trace.com/billing/customer-portal' \
-H 'accept: application/json' \
-H 'X-AccessToken: '

Example of success response:

{
  "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.