# Stop and restore service

Stop a customer's mobile data when they have used what they paid for, or suspend a lost phone's line, and restore either.

> Partner API · https://developer.telgea.com/docs/partner/guides/stop-and-restore-service

The Partner API gives you two levers on a customer's line. Pick by what happened:

| Situation                                   | Call                                                            | What stops                                          |
| ------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------- |
| The customer has used up what they paid for | [Stop mobile data](https://developer.telgea.com/docs/partner/api/numbers#stop-a-line-s-mobile-data) | Mobile data only; calls and texts keep working      |
| The phone is lost or stolen                 | [Suspend the line](https://developer.telgea.com/docs/partner/api/numbers#suspend-a-line)            | All traffic on the line, domestic and international |

Both act on one line, named in the path. Lines are listed by [`GET /v1/numbers`](https://developer.telgea.com/docs/partner/api/numbers#list-lines), and the `id` of each is what you name. Both return once the change has taken effect at the network, so a success means the service is genuinely stopped or restored. Nothing is queued for later. Both are real: there is no sandbox, and a call from the [playground](https://developer.telgea.com/playground) stops a real customer's service.

Neither lever is offered in every market. Check [Markets](https://developer.telgea.com/docs/partner/concepts/markets) before you offer one: where it says "Not supported", a stop returns `422` and a suspension `400`, and nothing changes. [Ending the line](https://developer.telgea.com/docs/partner/guides/end-a-plan) works everywhere.

## Stop and restore mobile data [#stop-and-restore-mobile-data]

Send the change with an optional `reason`. It is kept with the change and shown to Telgea support if the customer calls.

```bash
POST /v1/numbers/{numberId}/data-restriction
```

```json op="POST /v1/numbers/{numberId}/data-restriction" dir=request
{
  "reason": "Customer exceeded their agreed data allowance."
}
```

The response lists the numbers the stop reached and when it took effect:

```json op="POST /v1/numbers/{numberId}/data-restriction" dir=response status=200
{
  "numbers": ["+4520123456"],
  "effectiveAt": "2026-09-14T09:30:00.000Z"
}
```

* Stopping data that is already stopped returns `409` and changes nothing.
* A line in none of your data pools has no data to stop, and the call returns `422`.
* A line in a market that does not offer stopping data returns `422` as well. The error's `detail` says which of the two it was.
* Telgea's own automated processes never undo a stop you made. Only you restore it.

To restore data, send `DELETE` on the same path, with an optional `reason` query parameter:

```bash
DELETE /v1/numbers/{numberId}/data-restriction?reason=Top-up%20received
```

Restoring data that is not stopped returns `409`. Data stays off if the customer is also over an allowance you set; clear that first.

## Suspend and restore a line [#suspend-and-restore-a-line]

Suspension acts on the whole line, so there is nothing to send with it and nothing for the response to report: both calls answer `204`.

```bash
POST /v1/numbers/{numberId}/suspension
```

Suspending a line that is already suspended returns `409`. A line in a market that does not offer suspension returns `400` and stays live. To restore it, send `DELETE` on the same path:

```bash
DELETE /v1/numbers/{numberId}/suspension
```

## Permissions [#permissions]

Stopping data and suspending a line need `numbers:suspend` on your key; restoring either needs `numbers:unsuspend`.

## Deciding when to act [#deciding-when-to-act]

Watch what your customers use with the [usage feed and data pools](https://developer.telgea.com/docs/partner/guides/usage), and stop data when a customer reaches what they paid for. To end a customer's line for good rather than pause it, [end the line](https://developer.telgea.com/docs/partner/guides/end-a-plan) instead.

If a request times out, send it again with the same `Idempotency-Key` header: the API returns the original response instead of failing with a `409`. See [Retries and Idempotency](https://developer.telgea.com/docs/partner/guides#retries-and-idempotency).