> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexprice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Group Spend Alerts

> Monitor spend summed across every subscription line item whose feature belongs to a group, configured via API

Group spend alerts monitor the **usage-based spend summed across every line item on a subscription whose feature belongs to a given group**, for example every metered feature grouped under "Compute" or "Storage". This scope is useful when several distinct meters should count toward one shared budget, and is configured through the API.

## Prerequisite: Assign Features to the Group

A group's spend total only includes line items whose meter is backed by a **feature that has this group set as its `group_id`**. A feature with no group, or a different group, never contributes to this alert, even if it's on the same subscription.

<Warning>
  If none of a subscription's line items resolve to a feature in the configured group, the group total is `0` and the alert never fires. Confirm every feature you expect to count is assigned to the group before troubleshooting a group alert that isn't triggering.
</Warning>

<Steps>
  <Step title="Create a group">
    Create a group with **Entity type** set to **Feature**. See [Creating a group](/docs/product-catalogue/groups/create).
  </Step>

  <Step title="Assign each feature to the group">
    For every feature whose usage should count toward this alert, set its `group_id` to the group created above. See [Feature grouping](/docs/product-catalogue/groups/feature-grouping).
  </Step>
</Steps>

## Configuring via API

A group alert is always scoped to one subscription. The same group can have a different configuration (or no configuration) on a different subscription.

```json theme={null}
{
  "entity_type": "group",
  "entity_id": "group_01K7YQ0000GROUPID000001",
  "parent_entity_type": "subscription",
  "parent_entity_id": "subs_01K7YQ8ZR4M3V2N1XA9C6D0EFG",
  "config": {
    "alert_enabled": true,
    "warning":  { "threshold": "400", "condition": "above" },
    "critical": { "threshold": "800", "condition": "above" }
  }
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://api.cloud.flexprice.io/v1/alerts/setting' \
    -H 'x-api-key: <api_key>' \
    -H 'Content-Type: application/json' \
    -d '{
      "entity_type": "group",
      "entity_id": "group_01K7YQ0000GROUPID000001",
      "parent_entity_type": "subscription",
      "parent_entity_id": "subs_01K7YQ8ZR4M3V2N1XA9C6D0EFG",
      "config": {
        "alert_enabled": true,
        "warning":  { "threshold": "400", "condition": "above" },
        "critical": { "threshold": "800", "condition": "above" }
      }
    }'
  ```
</CodeGroup>

<Note>
  `parent_entity_type` and `parent_entity_id` are mandatory for group alerts. Unlike subscription-level alerts, a group alert cannot be unscoped.
</Note>

## Managing Alert Settings

### Viewing current configuration

<Steps>
  <Step title="Identify the alert setting">
    Query by `entity_type`, `entity_id`, and `parent_entity_id` to find the setting for this group and subscription.
  </Step>

  <Step title="Send the request">
    ```bash theme={null}
    curl -X POST 'https://api.cloud.flexprice.io/v1/alerts/setting/search' \
      -H 'x-api-key: <api_key>' \
      -H 'Content-Type: application/json' \
      -d '{
        "entity_type": "group",
        "entity_id": "group_01K7YQ0000GROUPID000001",
        "parent_entity_id": "subs_01K7YQ8ZR4M3V2N1XA9C6D0EFG"
      }'
    ```
  </Step>
</Steps>

### Changing thresholds

<Steps>
  <Step title="Build the complete config">
    Include every threshold you want to keep, not just the one you're changing.

    <Warning>
      The update replaces `config` entirely. It does not merge with what's stored. Send every threshold you want to keep on each update; a threshold left out is cleared.
    </Warning>
  </Step>

  <Step title="Send the request">
    `PUT /v1/alerts/setting/:id` with the complete desired `config`.
  </Step>
</Steps>

### Removing a threshold

<Steps>
  <Step title="Drop the threshold from config">
    Build the update payload with that threshold omitted and the others included as-is.
  </Step>

  <Step title="Send the request">
    `PUT /v1/alerts/setting/:id` with the trimmed `config`.
  </Step>
</Steps>

### Disabling alerts

<Steps>
  <Step title="Set alert_enabled to false">
    Build the update payload with `config.alert_enabled` set to `false`.
  </Step>

  <Step title="Send the request">
    `PUT /v1/alerts/setting/:id` with the updated `config`.
  </Step>
</Steps>

## Webhooks

| Event                                          | Fires when                |
| ---------------------------------------------- | ------------------------- |
| `subscription.group_spend.threshold_reached`   | Spend crosses a threshold |
| `subscription.group_spend.threshold_recovered` | Spend recovers to `ok`    |

<Info>
  Only groups actually touched by an event's usage are re-evaluated for that event.
</Info>

## Use Cases

* **Shared budgets across meters**: Alert once for combined spend across several related metered features (e.g. all compute-related meters) instead of tracking each individually
* **Product-line budgets**: Group features by product line and alert per line, independent of how many individual meters make it up
* **Consolidating noisy line items**: Roll up several low-value, high-frequency line items into one group threshold instead of alerting on each separately

## Related

* [What Are Spend Alerts?](/docs/subscriptions/how-to-configure-spend-alerts/what-are-spend-alerts): all three alert scopes, shared validation, and the full API reference
* [Subscription spend alerts](/docs/subscriptions/how-to-configure-spend-alerts/how-to-configure-subscription-spend-alerts): monitor the whole subscription
* [Line item spend alerts](/docs/subscriptions/how-to-configure-spend-alerts/how-to-configure-subscription-line-item-spend-alerts): monitor a single line item
* [Groups: Feature grouping](/docs/product-catalogue/groups/feature-grouping): assign features to a group
* [Webhooks](/docs/webhook/webhooks): endpoint setup, payload signatures, and retry behavior