> This page is for Docs.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://zuora.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://zuora.ferndocs.com/_mcp/server.

# Stop a meter

> Stop a running meter gracefully or immediately by using the API.

Stop a running meter gracefully or immediately by using the API.

The [Stop a specific version of a meter](https://developer.zuora.com/v1-api-reference/api/meters/stopmeterversion) API supports a graceful stop by default and an immediate Force Stop when required.

| Option                        | Behavior                                                                                                                       | Use when                                                                                                                        |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| Graceful Stop (default)       | Creates a savepoint before stopping the meter. When the meter is started again, it can resume from the saved processing state. | You want to preserve processing continuity, avoid loss of in-flight records, or resume the meter later.                         |
| Force Stop (`forceStop=true`) | Immediately cancels the running job without creating a savepoint.                                                              | The meter is stuck or unresponsive, a graceful stop is taking too long, or an operational incident requires immediate shutdown. |

A graceful stop may take longer to complete for a large or busy streaming meter because the system must save the current processing state before stopping. The meter normally moves from **Stopping** to **Paused**, or returns to **Running** if the graceful stop cannot be completed, within 30 minutes. If the meter remains in **Stopping** for more than 30 minutes, the system stops the meter after creating a savepoint.

> **Note**
>
> Use Force Stop only when immediate shutdown is more important than preserving the current processing state. Records that are being processed, as well as aggregations or intermediate state that has not been persisted, may be lost. A restarted meter resumes from the latest successfully completed savepoint, if one is available.

To request a Force Stop, set `forceStop=true` on the Stop Meter API request:

```
POST /meters/stop/{meterId}/{version}?forceStop=true
```

For the API request and response details, see the Stop a specific version of a meter API reference.

> **Note**
>
> Force Stop is not supported when a run is already in the **Stopping** state. The **Stopping** state is a temporary transition while the system is processing a graceful stop. In most cases, the run quickly either returns to **Running** if the graceful stop cannot be completed, or moves to its final terminal state. If a Force Stop is required, retry the operation after the run has exited the **Stopping** state.

## Force Stop statuses

The status after a Force Stop depends on the meter type.

| Meter type | Backend and API status | UI status       |
| ---------- | ---------------------- | --------------- |
| Streaming  | `FORCE_STOPPED`        | `FORCE_STOPPED` |
| Batch      | `CANCELED`             | `Stopped`       |

The different statuses reflect the recovery behavior. A Force Stop creates a distinct `FORCE_STOPPED` status for streaming meters because it cancels the job without creating a savepoint. For batch meters, a Force Stop has the same cancellation and recovery behavior as a normal stop, so the existing `CANCELED` status is used and displayed as **Stopped** in the UI.

A Force Stop immediately cancels the running job without creating a savepoint. Successfully processed data is not affected, but work that is in progress may not complete. When the meter is started again, it resumes from the latest successfully completed savepoint, if one is available. If no savepoint is available, the meter starts without the latest execution state.

## Example 1: Streaming API source

Suppose a streaming meter has processed Events 1001 and 1002 and is processing Event 1003. Events 1004 and 1005 are waiting to be processed.

* With a Graceful Stop, the meter completes Event 1003, creates a savepoint, and stops. When restarted, processing resumes with Event 1004.
* With a Force Stop, the meter is canceled while Event 1003 is in progress. Event 1003 might not complete. When restarted, the meter resumes from the latest available savepoint, such as the savepoint created after Event 1002, or from the configured source position if no savepoint exists.
* Depending on the source configuration, Event 1003 might need to be replayed, or it might be skipped if the source cannot replay previously delivered events.

## Example 2: Windowed aggregation

Consider a meter that aggregates API requests into one-minute windows. If a Force Stop occurs at 12:00:58 before the current window is completed or checkpointed, the partially completed aggregation can be discarded. After restart, the aggregation begins from the latest saved state. The affected window might contain fewer events than expected or require replay from the source. With a Graceful Stop, the aggregation state is saved before the meter stops.

## Example 3: Rating pipeline

Suppose a streaming meter performs the following: Source -> Enrichment -> Rating -> Billing. The rating pipeline has completed 50,000 events and has 500 additional events in progress. A Force Stop does not affect the 50,000 completed events, but some or all of the 500 in-flight events might not finish. After restart, those events might be replayed or might need to be resent, depending on the source's replay capabilities.

## Recommended stop option by scenario

| Scenario                                         | Recommended option |
| ------------------------------------------------ | ------------------ |
| Routine maintenance                              | Graceful Stop      |
| Pause and resume later                           | Graceful Stop      |
| Preserve processing state                        | Graceful Stop      |
| Meter is healthy                                 | Graceful Stop      |
| Meter is stuck or unresponsive                   | Force Stop         |
| Graceful Stop is taking too long                 | Force Stop         |
| Emergency shutdown                               | Force Stop         |
| Misconfigured meter                              | Force Stop         |
| Temporary or test meter that will not be resumed | Force Stop         |

* Use Graceful Stop whenever you expect to resume the meter later.
* Use Force Stop only when immediate shutdown takes priority over preserving the latest processing state.
* Before using Force Stop in production, understand whether the source can replay events. Sources that cannot replay may require manual intervention to recover in-flight events.

## Best practices for managing meter statuses

Use the following guidance when monitoring and stopping meter runs:

* Streaming meters continuously process incoming events and normally remain in **Running** until they are stopped.
* **Job Submission In Progress**, **Initializing**, and **Stopping** are transitional statuses. Allow the applicable operation time to complete before taking further action.
* When a meter is in **Stopping**, the system is processing a graceful stop and completing the required cleanup. The run normally either returns to **Running** if the graceful stop cannot be completed or moves to its final terminal state.
* Use Graceful Stop whenever you expect to resume the meter later. Graceful Stop preserves the current processing state by creating a savepoint before stopping.
* Use Force Stop only when immediate shutdown is more important than preserving the latest processing state. Before using Force Stop in production, verify whether the source can replay events. A source that cannot replay events might require manual intervention to recover events that were in progress.
* If a meter remains in **Stopping**, wait for the graceful-stop transition to complete. Do not issue Force Stop while the meter is in this state; retry only after the meter exits **Stopping**.
* Do not use Force Stop while a run is in **Stopping**. Wait until the run exits **Stopping**, then retry the Force Stop operation if necessary.
* After a successful Force Stop, successfully processed data is not affected. Work that was in progress may not complete. When you start the meter again, it resumes from the latest successfully completed savepoint, if one is available.
* If a meter remains in a transitional status longer than expected, review the run details and logs. Contact Zuora Support if the status does not progress.