Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mapping.travel/llms.txt

Use this file to discover all available pages before exploring further.

Two endpoints give you a complete picture of your organization’s billing arrangement. The subscription endpoint returns the raw Stripe subscription record, while the plan endpoint returns a usage-focused summary that includes how many matches you have used, remaining quota, and the cost accrued this month.
Both endpoints require authentication. Include your bearer token in the Authorization header.

​
GET /api/v1/billing/subscription

Retrieve your organization’s current Stripe subscription. 
GET https://api.mapping.travel/api/v1/billing/subscription
This endpoint returns the live subscription state from Stripe. If your organization is on the Free plan and has never completed a checkout, this returns null.

​
Response

​
id
string
Stripe subscription ID (e.g. sub_...).
​
status
string
Stripe subscription status. Common values: active, trialing, past_due, canceled.
​
planType
string
Internal plan type identifier (e.g. FREE, SUBSCRIPTION, ENTERPRISE).
​
currentPeriodStart
string
ISO 8601 timestamp of the start of the current billing period.
​
currentPeriodEnd
string
ISO 8601 timestamp of the end of the current billing period.
​
cancelAtPeriodEnd
boolean
Whether the subscription is set to cancel at the end of the current period.

​
Example

curl https://api.mapping.travel/api/v1/billing/subscription \
  -H "Authorization: Bearer <token>"

{
  "id": "sub_1ABC2DEF3GHI",
  "status": "active",
  "planType": "SUBSCRIPTION",
  "currentPeriodStart": "2026-04-01T00:00:00Z",
  "currentPeriodEnd": "2026-05-01T00:00:00Z",
  "cancelAtPeriodEnd": false
}

​
GET /api/v1/billing/plan

Retrieve usage-focused plan details for your organization. 
GET https://api.mapping.travel/api/v1/billing/plan
This endpoint returns a summary designed for dashboards and cost monitoring: what your plan allows, how much you have used, what you have spent, and how much quota you have remaining.

​
Response

​
planName
string
required
Internal plan identifier.
​
displayName
string
required
Human-readable plan name.
​
matchesPerMonth
number
required
Total mapping matches allowed per month on this plan.
​
pricePerMatch
number
required
Cost per individual match in euros.
​
matchesUsed
number
required
Number of matches consumed so far in the current billing period.
​
monthlyTotalCost
number
required
Total cost accrued in the current billing period in euros.
​
quotaRemaining
number
required
Number of matches remaining before the limit is reached.
​
usagePercentage
number
required
Percentage of the monthly quota that has been consumed. Value between 0 and 100.

​
Example

curl https://api.mapping.travel/api/v1/billing/plan \
  -H "Authorization: Bearer <token>"

{
  "planName": "SUBSCRIPTION",
  "displayName": "Growth",
  "matchesPerMonth": 150000,
  "pricePerMatch": 0.000001,
  "matchesUsed": 43200,
  "monthlyTotalCost": 0.0432,
  "quotaRemaining": 106800,
  "usagePercentage": 28.8
}
Poll this endpoint to build a usage progress bar in your dashboard. Combine it with GET /api/v1/billing/quota/status for real-time daily quota enforcement data.