Skip to main content
GET
/
subscriptions
List subscriptions
curl --request GET \
  --url https://api.alguna.io/subscriptions \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "billing": {
        "auto_issue_invoices": true,
        "auto_pay_invoices": false,
        "first_billing_date": "2026-01-01T00:00:00Z",
        "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"
      },
      "minimum_spend": {
        "amount": "500.00",
        "period": "monthly"
      },
      "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<int64>
required

Number of items per page

Example:

20

​
offset
integer<int64>
required

Number of items to skip

Example:

0

​
sort
string
required

Sort field and direction in format field:order

Example:

"activated_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
Example:

"active"

​
tag_ids
string[]

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

Example:

"tag_abc123"

Response

Success

​
data
object[]
required

List of subscriptions

​
pagination
object
required

Pagination metadata