# Subscription

Manage your Linked API subscription programmatically: check status and view or adjust seats.

Manage your Linked API subscription programmatically. For general Admin API information, see the [Admin overview](/docs/admin-overview).

## subscription.getStatus

Get current subscription status.

```bash
curl -X POST https://api.linkedapi.io/admin/subscription.getStatus \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here"
```

**Response:**

```json
{
  "success": true,
  "result": {
    "status": "active",
    "eligibleForTrial": false,
    "cancelAtPeriodEnd": false
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `status` | `string` or `undefined` | `active`, `trialing`, `past_due`, `canceled`, or `undefined` if no subscription |
| `eligibleForTrial` | `boolean` | Whether a 7-day free trial is available |
| `cancelAtPeriodEnd` | `boolean` | Whether the subscription is scheduled to cancel at the end of the current billing period |

## subscription.getSeats

Get active subscription seats.

```bash
curl -X POST https://api.linkedapi.io/admin/subscription.getSeats \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here"
```

**Response:**

```json
{
  "success": true,
  "result": {
    "seats": [
      {
        "seatType": "plus",
        "quantity": 10,
        "billingPeriod": "year"
      }
    ]
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `seatType` | `"core"` \| `"plus"` | Seat tier. `plus` unlocks Sales Navigator actions (`nv.*`) |
| `quantity` | `number` | Number of seats. Each seat allows one connected LinkedIn account |
| `billingPeriod` | `"month"` \| `"year"` | Billing cycle |

## subscription.setSeats

Set the number of subscription seats. If you already have an active subscription, the quantity is updated immediately. If not, a Stripe checkout link is returned.

New users can start with a 7-day free trial when they do not have any previous subscription history. The trial applies only when the initial checkout is eligible; otherwise checkout starts a regular paid subscription.

```bash
curl -X POST https://api.linkedapi.io/admin/subscription.setSeats \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{
    "quantity": 5,
    "billingPeriod": "year",
    "seatType": "plus"
  }'
```

**Body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `quantity` | `number` | Yes | Number of seats (1–1000) |
| `billingPeriod` | `"month"` \| `"year"` | Yes | Billing cycle |
| `seatType` | `"core"` \| `"plus"` | Yes | Seat tier |

**Response (subscription exists):**

```json
{
  "success": true,
  "result": {
    "status": "complete"
  }
}
```

**Response (no subscription, checkout required):**

```json
{
  "success": true,
  "result": {
    "status": "processing",
    "paymentLink": "https://checkout.stripe.com/..."
  }
}
```

> **Note:** When reducing seats below the number of connected accounts, excess accounts will be automatically frozen. Changes are applied in Stripe immediately but may take a few seconds to reflect in the API due to webhook processing.