Subscriptions API
Subscriptions connect customers to recurring products, billing periods, terms, and metered or licensed line items.
Endpoints
| Method |
Endpoint |
Description |
| GET |
/subscriptions |
List subscriptions |
| GET |
/subscriptions/{subscription_id} |
Retrieve a subscription |
The Subscription object
{
"id": 456,
"object": "subscription",
"customer_id": 123,
"status": "ACTIVE",
"title": "Acme Pro Plan",
"start_date": "2026-07-01T00:00:00Z",
"next_billing_date": "2026-08-01T00:00:00Z",
"billing_period": "MONTHLY",
"current_period_start": "2026-07-01T00:00:00Z",
"current_period_end": "2026-07-31T23:59:59Z",
"term_type": "EVERGREEN",
"initial_term_months": null,
"auto_renew": true,
"subscription_end_date": null,
"trial_end_date": null,
"cancel_at_period_end": false,
"canceled_at": null,
"ended_at": null,
"items": [
{
"id": 789,
"product_id": 42,
"product_name": "API Calls",
"quantity": 1,
"unit_price": "0.01000000",
"usage_type": "METERED",
"included_units": "10000.00000000"
}
],
"created_at": "2026-07-07T10:00:00Z",
"updated_at": "2026-07-07T10:00:00Z"
}
List subscriptions
curl https://api.floatless.com/api/public/v1/subscriptions?customer_id=123 \
-H "Authorization: Bearer sk_live_..."
Query parameters
| Parameter |
Type |
Description |
customer_id |
integer |
Filter by customer |
status |
string |
Filter by subscription status |
limit |
integer |
Number of results, 1 to 100 |
offset |
integer |
Pagination offset |
Retrieve a subscription
curl https://api.floatless.com/api/public/v1/subscriptions/456 \
-H "Authorization: Bearer sk_live_..."
Integration notes
- Use subscription item IDs when sending metered usage events.
- Use
usage_type to distinguish METERED lines from licensed quantity lines.
- Use
current_period_start and current_period_end when reconciling usage windows.
Next steps