> For the complete documentation index, see [llms.txt](https://docs.ipdunar.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipdunar.com/api-reference/subscriptions.md).

# Subscriptions

Subscriptions are recurring orders — typical for monthly traffic plans (residential / mobile) and monthly ISP renewals. The API mirrors what you'd configure in **Dashboard → Billing → Plans**.

## Endpoints

| Method  | Path                         | Purpose                                        |
| ------- | ---------------------------- | ---------------------------------------------- |
| `GET`   | `/subscriptions`             | List active subscriptions                      |
| `POST`  | `/subscriptions`             | Create a subscription                          |
| `GET`   | `/subscriptions/{id}`        | Get one                                        |
| `PATCH` | `/subscriptions/{id}`        | Modify quantity, plan tier, or cycle           |
| `POST`  | `/subscriptions/{id}/pause`  | Pause renewal (does not cancel current period) |
| `POST`  | `/subscriptions/{id}/cancel` | Cancel (effective end of period)               |

## List

```bash
curl -H "Authorization: Bearer API_KEY" \
     https://api.ipdunar.com/v1/subscriptions
```

Response:

```json
{
  "data": [
    {
      "id":           "sbn_01HX2K3PQ4M5",
      "product":      "residential",
      "plan":         "pro",
      "cycle":        "monthly",
      "gb_included":  500,
      "price_usd":    1500.00,
      "status":       "active",
      "renews_at":    "2026-06-01T00:00:00Z"
    },
    {
      "id":           "sbn_01HX2K4ABCD",
      "product":      "isp",
      "batch_id":     "bat_01HXabc",
      "cycle":        "annual",
      "quantity":     20,
      "price_usd":    1200.00,
      "status":       "active",
      "renews_at":    "2027-01-15T00:00:00Z"
    }
  ]
}
```

## Create — bandwidth subscription

```bash
curl -X POST -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "product": "residential",
       "plan":    "pro",
       "cycle":   "monthly"
     }' \
     https://api.ipdunar.com/v1/subscriptions
```

Plan tiers (residential): `starter` (50 GB), `pro` (500 GB), `business` (2000 GB), `enterprise` (custom). Mobile uses the same tier names but lower GB caps.

## Create — ISP renewal subscription

ISP batches are usually auto-renewing by default after the first order. To turn auto-renew on for an existing batch:

```bash
curl -X POST -H "Authorization: Bearer API_KEY" \
     -d '{
       "product":  "isp",
       "batch_id": "bat_01HXabc",
       "cycle":    "annual"           // or "monthly"
     }' \
     https://api.ipdunar.com/v1/subscriptions
```

Annual cycles get a 10% discount over equivalent monthly.

## Modify

Upgrade or downgrade:

```bash
curl -X PATCH -H "Authorization: Bearer API_KEY" \
     -d '{"plan": "business"}' \
     https://api.ipdunar.com/v1/subscriptions/sbn_01HX2K3PQ4M5
```

Upgrades are prorated for the current period. Downgrades take effect at the next renewal.

For ISP quantity changes:

```bash
curl -X PATCH -H "Authorization: Bearer API_KEY" \
     -d '{"quantity": 30}' \
     https://api.ipdunar.com/v1/subscriptions/sbn_01HX2K4ABCD
```

Quantity **increases** provision additional IPs immediately and are prorated. Decreases (releasing IPs) take effect at next renewal.

## Pause / cancel

```bash
# Pause — keep the current period's resources, don't renew
curl -X POST -H "Authorization: Bearer API_KEY" \
     https://api.ipdunar.com/v1/subscriptions/sbn_01HX/pause

# Cancel — same effect, plus the subscription is archived
curl -X POST -H "Authorization: Bearer API_KEY" \
     https://api.ipdunar.com/v1/subscriptions/sbn_01HX/cancel
```

After cancel, ISP batches enter the 7-day grace period documented in [IP management](https://docs.ipdunar.com/products/overview-2/ip-management.md#extend--renew).

## Errors

| Status | Code                    | Meaning                                                         |
| ------ | ----------------------- | --------------------------------------------------------------- |
| `409`  | `downgrade_below_usage` | Trying to downgrade below current period usage                  |
| `409`  | `already_subscribed`    | A subscription already exists for this product+plan combination |
| `422`  | `unknown_plan`          | Plan tier doesn't exist for this product                        |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ipdunar.com/api-reference/subscriptions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
