List subscriptions

Returns a paginated list of subscriptions. Supports filtering by status, customer ID, and tag IDs.

GET /subscriptions

List subscriptions

cURL

curl --request GET \
  --url https://api.alguna.io/subscriptions \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>'

200

{
  "data": [
    {
      "assignments": [
        {
          "type": "owner",
          "user_id": "usr_abc123"
        }
      ],
      "billing": {
        "auto_issue_invoices": true,
        "auto_pay_invoices": false,
        "payment_collection_method": "autopay",
        "autopay_timing": "on_due_date",
        "first_billing_date": "2026-01-01T00:00:00Z",
        "payment_method_id": "pm_01H1VECT",
        "payment_terms": "net_30"
      },
      "contract": {
        "period_type": "fixed",
        "duration_months": 12,
        "end_date": "2027-01-01T00:00:00Z",
        "start_date": "2026-01-01T00:00:00Z"
      },
      "created_at": "2025-12-15T10:30:00Z",
      "currency": "USD",
      "customer_id": "cust_abc123",
      "id": "sub_abc123",
      "metadata": {},
      "name": "Acme Corp - Enterprise",
      "pending_changes": [
        {
          "status": "draft",
          "version_id": "subv_abc123",
          "description": "Q3 upgrade",
          "effective_at": "2027-01-01T00:00:00Z"
        }
      ],
      "renewal": {
        "auto_renew": true,
        "duration_months": 12,
        "period_type": "fixed"
      },
      "status": "active",
      "updated_at": "2026-04-04T10:00:05Z",
      "activated_at": "2026-01-01T00:00:00Z",
      "current_version_id": "subv_abc123",
      "discount": {
        "amount": "10",
        "duration_type": "fixed",
        "type": "percentage",
        "duration_unit": "months",
        "duration_value": 6
      },
      "maximum_spend": {
        "amount": "500.00",
        "period": "monthly",
        "billing_direction": "arrears"
      },
      "minimum_spend": {
        "amount": "500.00",
        "period": "monthly",
        "billing_direction": "arrears"
      },
      "plan_id": "pln_abc123",
      "price_escalation": {
        "enabled": true,
        "interval_months": 12,
        "type": "percentage",
        "escalate_metered_unit_rates": false,
        "percentage": "5.00"
      },
      "trial_period_days": 30
    }
  ],
  "pagination": {
    "per_page": 20,
    "total_pages": 5
  }
}

Authorizations

Authorization · string · header · required

API key authentication. Pass your API key as a Bearer token.

Headers

Alguna-Version · enum<string> · required

Available options: 2026-04-01

Query Parameters

customer_id · string

Filter by customer ID

Example:

"cust_abc123"

limit · integer<int32>

Number of items per page

Required range: x <= 100

Example:

20

offset · integer<int32> · default: 0

Number of items to skip

Example:

0

sort · string

Sort field and direction in format field:order. Sortable fields: name, status, created_at, activated_at, ended_at, updated_at, contract_start_date, contract_end_date

Example:

"created_at:desc"

status · enum<string>[]

Filter by subscription status. Pass a comma-separated list to match any.

Available options: draft, scheduled, active, paused, canceled, completed, approved

Example:

"active"

tag_ids · string[]

Filter by tag IDs (comma-separated to match any)

Example:

"tag_abc123"

Response

200

application/json

Success

data · object[] · required

List of subscriptions

Show child attributes

pagination · object · required

Pagination metadata

Show child attributes