Get Subscription

Retrieve a specific subscription by ID

This endpoint retrieves detailed information about a specific subscription including plan details, billing history, and upcoming invoices.

Authentication

This endpoint requires a valid API key with subscriptions:read permissions.

Authorization: Bearer YOUR_API_KEY

Path Parameters

id · string · required

The unique identifier of the subscription

Query Parameters

expand · array

Expand related objects. Options: “customer”, “payment_method”, “invoices”, “upcoming_invoice”

Response

id · string

Unique subscription identifier

object · string

Object type, always “subscription”

status · string

Subscription status: “trialing”, “active”, “past_due”, “cancelled”, “unpaid”

current_period_start · string

Start of current billing period

current_period_end · string

End of current billing period

plan · object

Subscription plan details

cURL

curl --location 'https://api.stateset.com/v1/subscriptions/sub_0901f083-aa1c-43c5-af5c-0a9d2fc64e30?expand=upcoming_invoice' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response

{
  "id": "sub_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "object": "subscription",
  "customer_id": "cust_abc123",
  "status": "active",
  "created_at": "2024-01-19T17:00:00Z",
  "start_date": "2024-02-01",
  "current_period_start": "2024-02-01",
  "current_period_end": "2024-03-01",
  "trial_start": "2024-02-01",
  "trial_end": "2024-02-14",
  "plan": {
    "id": "plan_monthly_pro",
    "name": "Professional Monthly",
    "amount": 9900,
    "currency": "USD",
    "interval": "month",
    "interval_count": 1,
    "features": [
      "Unlimited orders",
      "Advanced analytics",
      "Priority support",
      "API access"
    ]
  },
  "items": [
    {
      "id": "si_123456",
      "product_id": "prod_addon_storage",
      "product_name": "Additional Storage (10GB)",
      "quantity": 2,
      "unit_price": 500,
      "amount": 1000
    }
  ],
  "quantity": 1,
  "subtotal": 10900,
  "tax_amount": 872,
  "total_amount": 11772,
  "payment_method_id": "pm_card_visa",
  "default_payment_method": {
    "id": "pm_card_visa",
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "4242",
      "exp_month": 12,
      "exp_year": 2025
    }
  },
  "shipping_address": {
    "line1": "123 Main St",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90001",
    "country": "US"
  },
  "next_invoice_date": "2024-03-01",
  "cancel_at_period_end": false,
  "upcoming_invoice": {
    "amount_due": 11772,
    "currency": "USD",
    "period_start": "2024-03-01",
    "period_end": "2024-04-01",
    "lines": [
      {
        "description": "Professional Monthly",
        "amount": 9900
      },
      {
        "description": "Additional Storage (10GB) × 2",
        "amount": 1000
      }
    ]
  },
  "metadata": {
    "sales_rep": "john_smith",
    "campaign": "Q1_2024"
  }
}