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

# Get Subscription

Get your current subscription status, including plan details, billing cycle, and credit caps.

Use this endpoint to check your billing status and what credits are available.

<Note>
  **Subscription lifecycle:** 1. After signup, status is `none` -- no data credits available. 2.
  After checkout, status is `active` -- full plan credits.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.v2.dealmachine.com/v1/subscription \
    -H "Authorization: Bearer dm_sk_live_xxx"
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.v2.dealmachine.com/v1/subscription', {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  });

  const subscription = await response.json();

  console.log(`Status: ${subscription.status}`);
  console.log(`Enrichment cap: ${subscription.credits.enrichment_cap}`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.v2.dealmachine.com/v1/subscription',
      headers={'Authorization': f'Bearer {api_key}'}
  )

  sub = response.json()
  print(f"Status: {sub['status']}")
  print(f"Plan: {sub['plan']['name']}")
  print(f"Enrichment cap: {sub['credits']['enrichment_cap']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Active (Paid) theme={null}
  {
    "status": "active",
    "plan": {
      "name": "Basic",
      "is_paid": true
    },
    "trial": {
      "is_trialing": false,
      "trial_end": null,
      "enrichment_credits": 0
    },
    "billing_cycle": {
      "start": "2026-04-01T00:00:00.000Z",
      "end": "2026-05-01T00:00:00.000Z"
    },
    "credits": {
      "base_enrichment_cap": 10000,
      "monthly_credit_grant_cap": 0,
      "monthly_enrichment_cap": 10000,
      "additional_enrichment_balance": 0,
      "enrichment_cap": 10000,
      "total_enrichment_cap": 10000,
      "total_enrichment_available": 9998,
      "ai_cap": 25000000,
      "base_ai_cap": 25000000,
      "monthly_ai_credit_grant_cap": 0,
      "monthly_ai_cap": 25000000
    }
  }
  ```

  ```json 200 No Subscription theme={null}
  {
    "status": "none",
    "plan": {
      "name": "No plan",
      "is_paid": false
    },
    "trial": {
      "is_trialing": false,
      "trial_end": null,
      "enrichment_credits": 0
    },
    "billing_cycle": {
      "start": "2020-01-01T00:00:00.000Z",
      "end": "2099-01-01T00:00:00.000Z"
    },
    "credits": {
      "enrichment_cap": 0,
      "total_enrichment_cap": 0,
      "total_enrichment_available": 0,
      "ai_cap": 5000000
    }
  }
  ```
</ResponseExample>

## Response Fields

| Field                                | Type           | Description                                                                                                 |
| ------------------------------------ | -------------- | ----------------------------------------------------------------------------------------------------------- |
| `status`                             | string         | Subscription status: `none`, `trialing`, `active`, `past_due`, `canceled`, `incomplete`, `unpaid`, `paused` |
| `plan.name`                          | string         | Plan name (e.g., "Basic", "Pro", "No plan")                                                                 |
| `plan.is_paid`                       | boolean        | `true` if the subscription is active and paid                                                               |
| `trial.is_trialing`                  | boolean        | `true` only for legacy Stripe subscriptions still in pre-billing status                                     |
| `trial.trial_end`                    | string \| null | ISO 8601 timestamp when that status ends (null otherwise)                                                   |
| `trial.enrichment_credits`           | number         | Data credits available in that status (0 otherwise)                                                         |
| `billing_cycle.start`                | string         | ISO 8601 start of the current billing cycle                                                                 |
| `billing_cycle.end`                  | string         | ISO 8601 end of the current billing cycle                                                                   |
| `credits.enrichment_cap`             | number         | Monthly data credits for this billing cycle                                                                 |
| `credits.total_enrichment_cap`       | number         | Total current-cycle capacity, including additional credits                                                  |
| `credits.total_enrichment_available` | number         | Live spendable data credits remaining                                                                       |
| `credits.ai_cap`                     | number         | Max AI credits (tokens) for this billing cycle                                                              |

<Note>
  Use `credits.total_enrichment_available` for eligibility checks. It is a live remaining balance.
  `credits.total_enrichment_cap` and `credits.enrichment_cap` are allowances, not balances.
</Note>

## Status Values

| Status     | Meaning                           | Can use API?  |
| ---------- | --------------------------------- | ------------- |
| `none`     | No subscription -- just signed up | No (403)      |
| `trialing` | Legacy pre-billing status         | Yes           |
| `active`   | Paid subscription                 | Yes           |
| `past_due` | Payment failed, grace period      | Yes (limited) |
| `canceled` | Subscription canceled             | No            |