---
title: "Admin \u2014 subscriptions"
path: reference/api/admin-subscriptions
status: published
---

# Admin — subscriptions

**7 endpoints** in this group. All paths are prefixed with `/api/v1`.

## Endpoints in this group

- [`POST /api/v1/admin/subscriptions`](#post-api-v1-admin-subscriptions) — Admin Create Subscription
- [`POST /api/v1/admin/subscriptions/bulk`](#post-api-v1-admin-subscriptions-bulk) — Admin Bulk Subscription Action
- [`POST /api/v1/admin/subscriptions/{subscription_id}/cancel`](#post-api-v1-admin-subscriptions-subscription-id-cancel) — Admin Cancel Subscription
- [`GET /api/v1/admin/subscriptions/{subscription_id}/history`](#get-api-v1-admin-subscriptions-subscription-id-history) — Admin Subscription History
- [`POST /api/v1/admin/subscriptions/{subscription_id}/override`](#post-api-v1-admin-subscriptions-subscription-id-override) — Admin Override Subscription
- [`POST /api/v1/admin/subscriptions/{subscription_id}/resume`](#post-api-v1-admin-subscriptions-subscription-id-resume) — Admin Resume Subscription
- [`POST /api/v1/admin/subscriptions/{subscription_id}/suspend`](#post-api-v1-admin-subscriptions-subscription-id-suspend) — Admin Suspend Subscription

---

### POST `/api/v1/admin/subscriptions` — Admin Create Subscription {#post-api-v1-admin-subscriptions}

**Parameters**:

- `authorization` (header, string, optional)


**Body**: `AdminSubscriptionCreateRequest` — {`tenant_id`, `partner_id`, `service_slug`, `plan_id` + 1 more}


**Responses**:

- `201` — Successful Response. Returns: `ApiResponse_SubscriptionResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### POST `/api/v1/admin/subscriptions/bulk` — Admin Bulk Subscription Action {#post-api-v1-admin-subscriptions-bulk}

Apply the same lifecycle action to many subscriptions at once.

Best-effort: per-row failures are reported back with the reason rather
than rolling back the whole batch.

**Parameters**:

- `authorization` (header, string, optional)


**Body**: `BulkActionRequest` — {`subscription_ids`, `action`, `reason`}


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_BulkActionResult_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### POST `/api/v1/admin/subscriptions/{subscription_id}/cancel` — Admin Cancel Subscription {#post-api-v1-admin-subscriptions-subscription-id-cancel}

Cancel a subscription. Default is end-of-period (sets status='cancelling',
cancel_requested_at=now); set immediate=true to terminate right away.

**Parameters**:

- `subscription_id` (path, string, required)
- `authorization` (header, string, optional)


**Body**: `CancelRequest` — {`immediate`, `reason`}


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_SubscriptionResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### GET `/api/v1/admin/subscriptions/{subscription_id}/history` — Admin Subscription History {#get-api-v1-admin-subscriptions-subscription-id-history}

Audit-log entries scoped to this subscription, newest first.

**Parameters**:

- `subscription_id` (path, string, required)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_list_SubscriptionHistoryEntry__` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### POST `/api/v1/admin/subscriptions/{subscription_id}/override` — Admin Override Subscription {#post-api-v1-admin-subscriptions-subscription-id-override}

**Parameters**:

- `subscription_id` (path, string, required)
- `authorization` (header, string, optional)


**Body**: `AdminSubscriptionOverrideRequest` — {`plan_id`, `status`}


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_SubscriptionResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### POST `/api/v1/admin/subscriptions/{subscription_id}/resume` — Admin Resume Subscription {#post-api-v1-admin-subscriptions-subscription-id-resume}

Bring a subscription back to 'active' from 'cancelling' or 'suspended'.

**Parameters**:

- `subscription_id` (path, string, required)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_SubscriptionResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### POST `/api/v1/admin/subscriptions/{subscription_id}/suspend` — Admin Suspend Subscription {#post-api-v1-admin-subscriptions-subscription-id-suspend}

Suspend an active subscription (admin-driven pause).

**Parameters**:

- `subscription_id` (path, string, required)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_SubscriptionResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}