> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Subscription

> Retrieve a specific subscription by ID

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

## Authentication

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

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the subscription
</ParamField>

## Query Parameters

<ParamField query="expand" type="array">
  Expand related objects. Options: "customer", "payment\_method", "invoices", "upcoming\_invoice"
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique subscription identifier
</ResponseField>

<ResponseField name="object" type="string">
  Object type, always "subscription"
</ResponseField>

<ResponseField name="status" type="string">
  Subscription status: "trialing", "active", "past\_due", "cancelled", "unpaid"
</ResponseField>

<ResponseField name="current_period_start" type="string">
  Start of current billing period
</ResponseField>

<ResponseField name="current_period_end" type="string">
  End of current billing period
</ResponseField>

<ResponseField name="plan" type="object">
  Subscription plan details
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location 'https://api.stateset.com/v1/subscriptions/sub_0901f083-aa1c-43c5-af5c-0a9d2fc64e30?expand=upcoming_invoice' \
  --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript Node.js theme={null}
  const subscription = await stateset.subscriptions.retrieve(
    'sub_0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
    { expand: ['upcoming_invoice'] }
  );
  ```

  ```python Python theme={null}
  subscription = stateset.subscriptions.retrieve(
    'sub_0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
    expand=['upcoming_invoice']
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>