> Documentation index: https://docs.sellhidden.com/llms.txt

# Subscriptions

Source: https://docs.sellhidden.com/reference/subscriptions

Buyers of a variation billed per period (weekly to yearly). Renewals are fresh orders the buyer pays from the renewal email or the order page, or from their store balance; after the grace period access ends by itself. The subscription.* webhook events carry the same shape.

## Endpoints

4 endpoints · [subscriptions:read](https://docs.sellhidden.com/start?scope=subscriptions%3Aread#scopes) · [subscriptions:write](https://docs.sellhidden.com/start?scope=subscriptions%3Awrite#scopes)

Base URL https://api.sellhidden.com/v1 · Authorization: Bearer · 120/min per key · cursor pagination · Idempotency-Key on POST · No test mode

### GET /subscriptions — List subscriptions

Scope `subscriptions:read`.

**Query parameters**

| Query parameters | Type | Description |
| --- | --- | --- |
| `status` | trialing \| active \| past_due \| cancelled \| expired | Only this status. |
| `email` | string | Buyer email contains this text. |
| `product` | string | Product id. |
| `limit` | 1..100 | Page size. Default 25. |
| `cursor` | string | nextCursor from the previous page. |

```bash
curl https://api.sellhidden.com/v1/subscriptions \
  -H "Authorization: Bearer hsk_live_…"
```

Response (200):

```json
{ "ok": true, "subscriptions": [ { "subscriptionId": "clx…", "status": "active", "buyerEmail": "jo@example.com", "productId": "clx…", "productTitle": "Pro plan", "variantId": "clx…", "quantity": 1, "priceUsd": 9, "interval": "month", "currentPeriodStart": "…", "currentPeriodEnd": "…", "graceEndsAt": "…", "cancelAtPeriodEnd": false, "autoRenewFromBalance": false, "initialOrderId": "clx…", "renewalOrderId": null, "renewals": 2, "endedAt": null, "createdAt": "…" } ], "nextCursor": null, "hasMore": false }
```

### GET /subscriptions/{id} — Get a subscription

Scope `subscriptions:read`.

```bash
curl https://api.sellhidden.com/v1/subscriptions/ID \
  -H "Authorization: Bearer hsk_live_…"
```

### POST /subscriptions/{id}/cancel — Cancel a subscription

By default the buyer keeps access until the period end and nothing more is charged (cancelAtPeriodEnd). With immediate: true access ends now: Discord roles are removed, the pending renewal order is cancelled and subscription.expired is sent with the keys it delivered. Scope `subscriptions:write`. Accepts `Idempotency-Key`.

**Body**

| Body | Type | Description |
| --- | --- | --- |
| `immediate` | boolean | End now instead of at the period end. Default false. |

```bash
curl -X POST \
  https://api.sellhidden.com/v1/subscriptions/ID/cancel \
  -H "Authorization: Bearer hsk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'
```

### POST /subscriptions/{id}/extend — Extend by one period

Adds one billing period for free from the current end (or from now when it already ended) and brings an expired or cancelled subscription back, Discord roles included. Scope `subscriptions:write`. Accepts `Idempotency-Key`.

```bash
curl -X POST \
  https://api.sellhidden.com/v1/subscriptions/ID/extend \
  -H "Authorization: Bearer hsk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'
```