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

Subscription enums are lowercase: status trialing | active | paused | canceled | past_due | unpaid | expired | pending, term_type evergreen | termed, usage_type licensed | metered, billing_period monthly | quarterly | annually.

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

• Usage events API
• Invoices API
• Webhooks