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

# Overview

> Plans, their quotas and credit rates, and your project's subscriptions.

The **Subscriptions** API lists the plans available on the platform and the
subscriptions your project holds. A subscription ties your project to a plan on a
billing cycle.

## Lifecycle

Subscriptions are read-only here: they are **created by paying**, through the
[Payments](/api-reference/payments/create-deposit-account) API:

* **Subscribe**: [create a deposit account](/api-reference/payments/create-deposit-account)
  for the plan and pay it. Settlement creates the subscription `ACTIVE` for one
  billing period and grants the plan's product access. Free (\$0) plans activate
  immediately, no payment needed.
* **Renew**: pay for the same `planId` again; the existing subscription's period
  is extended. Subscriptions past `endDate` become `EXPIRED` (after a short grace
  window).
* **Upgrade**: pay for a different plan of the same product while this one is
  active. The charge is prorated for your unused time, the new subscription starts
  fresh, and the old one moves to `CANCELLED`. See
  [Fund and subscribe](/guides/fund-and-subscribe#4-renewals-and-upgrades).

## The plan object

| Attribute      | Type          | Description                                        |
| -------------- | ------------- | -------------------------------------------------- |
| `id`           | `integer`     | Unique plan id.                                    |
| `name`         | `string`      | Display name (e.g. `Starter`).                     |
| `description`  | `string`      | What the plan includes.                            |
| `isActive`     | `boolean`     | Whether the plan can be subscribed to.             |
| `type`         | `string`      | `SUBSCRIPTION` (fixed price) or `USAGE` (metered). |
| `productId`    | `integer`     | Product the plan belongs to.                       |
| `priceMonthly` | `number`      | Monthly price in fiat major units.                 |
| `creditRate`   | `object`      | Per-metric credit rates, for `USAGE` plans.        |
| `planQuotas`   | `PlanQuota[]` | Usage limits attached to the plan (see below).     |
| `createdBy`    | `string`      | Actor that created the plan.                       |
| `createdAt`    | `string`      | ISO 8601 UTC timestamp.                            |

### The plan quota object

| Attribute       | Type              | Description                                                      |
| --------------- | ----------------- | ---------------------------------------------------------------- |
| `id`            | `string`          | Unique quota id.                                                 |
| `planId`        | `integer`         | Plan the quota belongs to.                                       |
| `metric`        | `string`          | Metered dimension (e.g. `API_CALLS`, `PROJECTS`, `TOKEN_MINTS`). |
| `limitValue`    | `integer \| null` | Cap for the metric; `null` means unlimited.                      |
| `windowSeconds` | `integer \| null` | Rolling window in seconds; `null` means no window.               |

## The subscription object

| Attribute          | Type             | Description                                                                                                   |
| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------- |
| `id`               | `string`         | Unique subscription id.                                                                                       |
| `projectId`        | `string`         | Project that owns the subscription.                                                                           |
| `businessId`       | `string`         | Owning business.                                                                                              |
| `planId`           | `integer`        | Subscribed plan.                                                                                              |
| `billingCycle`     | `string \| null` | `MONTHLY` or `YEARLY`; `null` for usage plans.                                                                |
| `status`           | `string`         | `ACTIVE`, `EXPIRED` (period lapsed), `CANCELLED` (ended, including superseded by an upgrade), or `SUSPENDED`. |
| `subscriptionType` | `string`         | e.g. `EXTERNAL`.                                                                                              |
| `startDate`        | `string`         | ISO 8601 UTC start.                                                                                           |
| `endDate`          | `string \| null` | ISO 8601 UTC end, or `null` if open-ended.                                                                    |
| `autoRenew`        | `boolean`        | Whether the subscription renews automatically.                                                                |
| `creditAmount`     | `number \| null` | Remaining credits, for usage plans.                                                                           |
| `paymentRef`       | `string`         | Reference of the payment that activated it.                                                                   |
| `createdBy`        | `string`         | Actor that created the subscription.                                                                          |
| `createdAt`        | `string`         | ISO 8601 UTC timestamp.                                                                                       |
| `updatedAt`        | `string`         | ISO 8601 UTC timestamp.                                                                                       |