> ## Documentation Index > Fetch the complete documentation index at: https://docs.recurso.dev/llms.txt > Use this file to discover all available pages before exploring further. # Update Usage Alert > Re-aim an existing usage alert at a new threshold type and value. Changes the threshold an alert fires at. The subscription and metric are the alert's identity — to point an alert at a different subscription or metric, [delete it](/api-reference/usage-alerts/delete) and [create a new one](/api-reference/usage-alerts/create). Updating clears the alert's per-period "already fired" marker (`last_fired_period_start`), so the new threshold can fire in the current billing period even if the old one already did. ## Parameters | Parameter | Type | Required | Description | | --------- | ------------- | -------- | ------------------------------------------------- | | `id` | string (UUID) | Yes | Usage alert ID (path). Must belong to your tenant | ## Request Body | Parameter | Type | Required | Description | | ---------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `threshold_type` | string | Yes | `quantity` (an absolute metered quantity) or `percent_of_limit` (a percentage of the subscription's entitlement limit) | | `threshold` | integer | Yes | Must be greater than `0`. For `percent_of_limit` at most `1000`; values above `100` alert on overage | ## Example Request ```bash theme={null} curl -X PUT https://api.recurso.dev/v1/usage-alerts/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "threshold_type": "percent_of_limit", "threshold": 90 }' ``` ## Response The response echoes the alert's `id` and the new threshold. The handler does not re-read the row after the update, so `subscription_id`, `metric_code`, `created_at` and `updated_at` come back zero-valued here — use [List Usage Alerts](/api-reference/usage-alerts/list) to read the full object. ```json theme={null} { "data": { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "tenant_id": "2b9e1c44-7d3a-4f6b-8e21-5c0d9a7f1b33", "subscription_id": "00000000-0000-0000-0000-000000000000", "metric_code": "", "threshold_type": "percent_of_limit", "threshold": 90, "created_at": "0001-01-01T00:00:00Z", "updated_at": "0001-01-01T00:00:00Z" } } ``` ## Fields | Field | Type | Description | | ------------------------------------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------- | | `id` | string (UUID) | The alert that was updated | | `tenant_id` | string (UUID) | Owning tenant | | `threshold_type` | string | The new `quantity` or `percent_of_limit` | | `threshold` | integer | The new threshold value | | `subscription_id`, `metric_code`, `created_at`, `updated_at` | — | Not populated by this endpoint (see above); `last_fired_period_start` is omitted because the update resets it to `null` | ## Errors | Status | Code | When | Fix | | ------ | ------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | `400` | `validation_failed` | `id` is not a valid UUID, or the body is malformed / missing `threshold_type` or `threshold` | Pass the alert's UUID and both required fields | | `400` | `validation_failed` | `threshold_type` is not `quantity` or `percent_of_limit` | Use one of the two values | | `400` | `validation_failed` | `threshold` is not positive, or a `percent_of_limit` threshold exceeds `1000` | Send a positive integer (percent thresholds at most `1000`) | | `401` | `unauthorized` | Missing or invalid API key / session | Send `Authorization: Bearer $API_KEY` | | `404` | `not_found` | No usage alert with that ID in your tenant | Check the ID against [List Usage Alerts](/api-reference/usage-alerts/list) | | `409` | `conflict` | Another alert on the same subscription and metric already has this exact threshold | Edit or delete the duplicate instead | | `500` | `internal_error` | Persisting the update failed | Retry; contact support if it persists | Errors use the standard envelope — see [Errors](/api-reference/errors). ## OpenAPI ````yaml PUT /v1/usage-alerts/{id} openapi: 3.1.0 info: title: Recurso API version: 1.0.0 description: | The Recurso billing engine REST API. Authenticate by passing your API key as a bearer token: Authorization: Bearer Obtain an API key by registering a tenant via `POST /auth/register`. All authenticated endpoints live under the `/v1` prefix. Mutating endpoints support idempotency via the `Idempotency-Key` header. license: name: MIT identifier: MIT servers: - url: https://billing.example.com description: >- Example deployment — substitute the base URL of your own Recurso deployment. security: - bearerAuth: [] tags: - name: System description: Health, version, and API metadata - name: Auth description: Tenant registration - name: Plans description: Product catalog plans - name: Customers description: Customer management - name: Subscriptions description: Subscription lifecycle - name: Invoices description: Invoices, PDFs, and Indian GST e-invoicing - name: Coupons description: Discounts - name: Usage description: Metered usage events - name: Credit Notes description: Customer credits - name: Quotes description: Quote-to-invoice lifecycle - name: Webhooks description: Webhook endpoint management and event feed - name: Analytics description: Revenue analytics - name: Checkout description: Public hosted checkout for invoices - name: Payments description: Payment order creation - name: Inbound Webhooks description: Receivers for payment-gateway callbacks (Razorpay, Stripe) - name: Customer Portal description: Customer-facing portal — magic-link auth and session-scoped data - name: Developer description: API key management - name: Account description: Tenant account settings - name: Finance description: Ledger accounts, entries, reconciliation, and revenue recognition - name: Settings description: Tax (GST) and e-invoicing (IRP) configuration - name: Consents description: Consent records for RBI-compliant recurring billing - name: Referrals description: Customer referral program - name: Gifts description: Gift subscriptions - name: Mandates description: UPI Autopay mandates - name: Offline Payments description: Virtual accounts and manually recorded payments - name: Organizations description: Multi-entity organizations grouping several tenants - name: Accounting description: QuickBooks / Xero accounting integrations - name: Churn description: Churn risk scoring and alerts - name: Cancel Flows description: Configurable retention flows shown at cancellation time - name: Dunning description: Dunning analytics and multi-channel dunning campaigns paths: /v1/usage-alerts/{id}: put: tags: - Metering summary: Edit a usage alert's threshold description: >- Re-aims an existing alert at a new threshold (type and value). Subscription and metric are the alert's identity — to change those, delete and re-create. Editing resets the per-period fired dedup so the new threshold can fire in the current billing period. operationId: updateUsageAlert parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: - threshold_type - threshold properties: threshold_type: type: string enum: - quantity - percent_of_limit threshold: type: integer format: int64 exclusiveMinimum: 0 responses: '200': description: The updated alert content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/UsageAlert' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': description: An identical alert already exists for the subscription + metric. components: schemas: UsageAlert: type: object description: A usage threshold that fires once per billing period. properties: id: type: string format: uuid subscription_id: type: string format: uuid metric_code: type: string threshold_type: type: string enum: - quantity - percent_of_limit threshold: type: integer format: int64 last_fired_period_start: type: - string - 'null' format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time Error: type: object required: - error properties: error: type: object description: Structured error detail. required: - code - message properties: code: type: string description: Stable machine-readable error code. examples: - validation_failed - unauthorized - forbidden - not_found - conflict - rate_limited - internal_error - invalid_api_key - key_mode_mismatch - over_refund - invoice_not_paid - invoice_already_paid message: type: string description: Human-readable explanation. responses: BadRequest: description: The request body or parameters are invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid credentials (API key or session cookie). content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Tenant API key obtained from `POST /auth/register` or `POST /v1/developer/keys`. ````