> Parel documentation. Index of every page: https://parel.si/docs/llms.txt. This page in HTML: https://parel.si/docs/api/topups

# Top-ups

> Purchases are off during the closed beta; credit is added on request. What GET /v1/packs and POST /v1/topup return meanwhile, and the how_to_get_credit field.

## During the beta

Parel is in a closed beta and **purchases are off**. Every new team receives ₹100 of welcome credit automatically. More credit is added by Parel on request: email [hello@parel.si](mailto:hello@parel.si) with the team name. Failed calls are ₹0, so a retry never needs credit.

## The field that tells an agent what to do

Two responses carry a `how_to_get_credit` string written for the agent to repeat to the user:

- the MCP tool `check_balance`, always;
- [`insufficient_balance`](https://parel.si/docs/errors.md#insufficient_balance) (HTTP 402) from any paid call.

Its text depends on whether a payment provider is configured on the server. During the beta it reads:

```text
During the beta, credit is added by Parel on request: email hello@parel.si with the team name. Nothing is charged for failed calls.
```

When purchases open it will read `Top up at <topup_url>.` An agent should show the sentence and stop; retrying does not change the balance. The `insufficient_balance` body also carries `estimate_paise` (the hold that was needed), `balance_paise` and `topup_url`.

## GET /v1/packs

Scope `read`. Lists the fixed top-up packs: the credit each adds and what it will cost, in paise, with the payment fee included in the price. The list exists today so clients can be built against it; buying is not possible until purchases open.

```json
{
  "ok": true,
  "packs": [
    {
      "id": "500",
      "credit_paise": 50000,
      "price_paise": 53000
    },
    {
      "id": "2000",
      "credit_paise": 200000,
      "price_paise": 212000
    },
    {
      "id": "5000",
      "credit_paise": 500000,
      "price_paise": 530000
    }
  ]
}
```

## POST /v1/topup

Scope `read`. Body `{"pack": "500"}` with an id from `packs[]`; an unknown id is [`unknown_pack`](https://parel.si/docs/errors.md#unknown_pack) (400) with the valid ids. While purchases are off every valid request answers [`payments_not_configured`](https://parel.si/docs/errors.md#payments_not_configured) (HTTP 503). Captured from staging:

```json
{
  "ok": false,
  "error": "payments_not_configured",
  "message": "Top-ups are not enabled yet.",
  "request_id": "8796af11-6a3a-489b-968e-fccb8b7fa27c"
}
```

When purchases open, a successful call returns `pack`, `price_paise`, `credit_paise`, `checkout_url` and `session_id`; the balance is credited only when the payment provider confirms the payment, and a payment that does not match the pack is never credited automatically. The [Refund Policy](https://parel.si/legal/refunds) covers unused paid credit; promotional credit, including the welcome credit, is never refunded.
