Plans and Billing API

Every tracker requires an active plan. Use these endpoints to present pricing, read the subscriptions attached to your account, hand customers off to the payment portal, and manage device licenses.

All endpoints require the standard credentials:

x-api-key: <YOUR_API_KEY>
Authorization: Bearer <JWT_TOKEN>

Plan model

Name
id
Type
integer
Description
Internal plan ID.
Name
title
Type
string
Description
Plan name.
Name
description
Type
text
Description
Plan description.
Name
price
Type
integer
Description
Price in the smallest currency unit.
Name
stripe_product_id
Type
string
Description
Stripe price identifier used at checkout.
Name
features
Type
object
Description
Structured feature list.
Name
trial_months
Type
integer
Description
Free trial length in months. Defaults to 2.
Name
manual
Type
boolean
Description
Whether this plan is assigned manually rather than sold online. Defaults to false.

Plans

Name
GET /api/plans
Description
List available plans.
Name
GET /api/plans/:id
Description
Get one plan.

Plans are read-only from the API. Contact Livepin to have a plan added or changed.

List plans

curl "$LIVEPIN_API_BASE_URL/api/plans" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Response (trimmed)

{
  "data": [
    {
      "id": 3,
      "attributes": {
        "title": "Annual Tracking",
        "description": "12 months of tracking and alerts",
        "price": 240000,
        "stripe_product_id": "price_1Pxxxxxxxxxxxx",
        "features": { "dashcam": true, "fuelMonitoring": false },
        "trial_months": 2,
        "manual": false
      }
    }
  ],
  "meta": { "pagination": { "page": 1, "pageSize": 25, "pageCount": 1, "total": 1 } }
}

Subscription model

Name
id
Type
integer
Description
Internal subscription ID.
Name
user
Type
object
Description
Subscribing user.
Name
plan
Type
object
Description
Subscribed plan.
Name
device
Type
object
Description
Device the subscription is attached to.
Name
start_time
Type
datetime
Description
Subscription start.
Name
active
Type
boolean
Description
Whether the subscription is active. Defaults to false.

Subscriptions

Name
GET /api/subscriptions
Description
List subscriptions.
Name
GET /api/subscriptions/:id
Description
Get one subscription.

List subscriptions

curl "$LIVEPIN_API_BASE_URL/api/subscriptions" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Response (trimmed)

{
  "data": [
    {
      "id": 145,
      "attributes": {
        "start_time": "2026-01-01T00:00:00.000Z",
        "active": true,
        "plan": { "data": { "id": 3, "attributes": { "title": "Annual Tracking" } } },
        "device": { "data": { "id": 41, "attributes": { "imei": "352592573176740" } } }
      }
    }
  ],
  "meta": { "pagination": { "page": 1, "pageSize": 25, "pageCount": 1, "total": 1 } }
}

Billing portal

Generate a hosted Stripe billing portal URL so a customer can update their payment method, download invoices, or cancel a subscription without leaving your product.

Name
GET /api/subscriptions/billing-portal
Description
Returns { "url": ... } for the current user's Stripe customer.

The first call for a user creates the Stripe customer record if one does not already exist. Redirect the customer to the returned URL immediately — portal sessions are short lived. After the customer finishes, Stripe returns them to https://livepin.in.

Request

curl "$LIVEPIN_API_BASE_URL/api/subscriptions/billing-portal" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Response

{
  "url": "https://billing.stripe.com/p/session/test_xxxxxxxxxxxxxxxx"
}

Licenses

A license binds a device to a vehicle under a dealer. Licenses carry the renewal date, which drives the expiry alerts returned by GET /api/vehicles/reports/expiry-report.

Name
GET /api/licenses
Description
List licenses.
Name
GET /api/licenses/:id
Description
Get one license with device, vehicle, and owner populated.
Name
PUT /api/licenses/:id
Description
Update the device and vehicle fields attached to a license.
Name
POST /api/licenses
Description
Create a license.
Name
DELETE /api/licenses/:id
Description
Delete a license.

License model

Name
licenseId
Type
string
Description
Required, unique. License identifier.
Name
device
Type
object
Description
Licensed device.
Name
vehicle
Type
object
Description
Licensed vehicle.
Name
owner
Type
object
Description
Owning dealer.
Name
expiry
Type
date
Description
License expiry date.
Name
cost
Type
integer
Description
License cost.

Updatable fields

Name
vehicle_no
Type
string
Description
Written to the linked vehicle.
Name
vehicle_type
Type
string
Description
Written to the linked vehicle.
Name
fuel_calibration
Type
object
Description
Written to the linked vehicle.
Name
max_fuel_litres
Type
number
Description
Written to the linked vehicle.
Name
imei
Type
string
Description
Written to the linked device.
Name
sim_no
Type
string
Description
Written to the linked device.
Name
sim_provider
Type
string
Description
Written to the linked device.
Name
relay_control
Type
boolean
Description
Written to the linked device.
Name
on_demand_tracking
Type
boolean
Description
Written to the linked device.
Name
fuel_monitoring
Type
boolean
Description
Written to the linked device.
Name
buzzer_sound
Type
boolean
Description
Written to the linked device.
Name
is_dashcam
Type
boolean
Description
Written to the linked device.
Name
dashcam_total_channels
Type
integer
Description
Written to the linked device.

Get license

GET

/api/licenses/:id

curl "$LIVEPIN_API_BASE_URL/api/licenses/145" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

PUT sends a flat body — unlike the collection endpoints above, do not wrap it in data.

Update license

PUT

/api/licenses/:id

curl -X PUT "$LIVEPIN_API_BASE_URL/api/licenses/145" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicle_no": "DUMMY-VEHICLE-302",
    "imei": "352592573176741",
    "fuel_monitoring": true
  }'

GET and PUT /api/licenses/:id are available to DEALER accounts. Only the dealer that owns the license may update it.

Continue to Reference Data