---
title: "Get User Plan Details"
method: GET
path: "/api/v1/subscriptions/plan-details"
tags: ["Subscriptions", "Subscriptions"]
---

# Get User Plan Details

`GET /api/v1/subscriptions/plan-details`

## Request

- Base URL: `https://api.gemstoneaiapp.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gemstoneaiapp.com/api/v1/subscriptions/plan-details`
- Auth: HTTP bearer

**📋 COMPLETE PLAN DETAILS - Use this for detailed displays**

Get full plan information including:
- All plan features (categorized)
- Usage statistics
- Billing information
- Plan metadata

**Perfect for:**
- Account/Settings page
- Plan comparison modals
- Upgrade prompts with feature lists
- Subscription management page

**Response includes:**
- Full plan details with all features
- Usage stats (scans used, gems count)
- Billing info (price, next billing date)
- All plan features categorized (Scanning, Analysis, Collection, etc.)

**Example Usage:**
```javascript
// Call when user opens settings or subscription page
const details = await fetch('/api/v1/subscriptions/plan-details', {
  headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());

// Display full plan info
console.log(details.plan_display_name); // "Free" or "Premium"
console.log(details.features); // All categorized features
console.log(details.price); // "$29.99/monthly"
```

**More Complete** - Returns all plan information for detailed displays.

## Response `200`

Successful Response

- UserPlanDetailsResponse: Complete plan details including all features and metadata. Use this API when displaying: - Plan comparison pages - Settings/account page - Upgrade prompts with feature lists Perfect for: Full plan info display, settings page, upgrade modals
  - `plan_id` integer, required
  - `plan_name` string, required: Internal name: 'free' or 'premium'
  - `plan_display_name` string, required: Display name: 'Free' or 'Premium'
  - `description` string, nullable: Plan description
  - `is_active` boolean, required: Is subscription currently active?
  - `status` string, required: active, cancelled, expired, past_due
  - `scans_used_this_month` integer, required
  - `scans_remaining` union, required
    - string
    - integer
  - `scans_limit` integer, nullable, required
  - `collection_count` integer, required
  - `collection_slots_remaining` union, required
    - string
    - integer
  - `collection_limit` integer, nullable, required
  - `features` object, nullable: Categorized features: {category: [{feature, value}]}
  - `billing_period` string, nullable
  - `price` string, nullable
  - `next_billing_date` string, date-time, nullable
  - `cancel_at_period_end` boolean
  - `subscription_start_date` string, date-time, nullable
  - `current_period_end` string, date-time, nullable
  - `scan_tier` ScanTierQuota: Monthly allowance of a capped paid tier (LNK-SCANTIERS). Null on free plans and on unlimited (pre-tier) Premium.
    - `tier` string, required
    - `scans_used` integer, required
    - `scans_limit` integer, required
    - `scans_remaining` integer, required
    - `resets_at` string, required
    - `upgrade_tier` string, nullable

---

[API](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api.md) · [All operations](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api/revisions/fcb441f55161?raw)