# Alerts List, retrieve, and action network alerts for accessible organisations. {% hint style="info" %} **Verifi RDR alerts are resolved automatically.** Verifi RDR alerts arrive with status `RESOLVED` or `INVALID` and do not require actioning. The `ACTION_REQUIRED` status and the PATCH endpoint for actioning alerts apply to Ethoca alerts only. {% endhint %} {% hint style="danger" %} **Ethoca alerts in `ACTION_REQUIRED` status must be actioned.** Refunding the transaction alone is not enough to prevent a chargeback. You must also action the alert using the PATCH endpoint so that Ethoca is notified and can stop the dispute. Unactioned alerts provide no value — the chargeback will proceed regardless of whether you refunded the customer. If you have resolution rules configured, matching alerts are resolved automatically. In rare cases, an alert may still appear as `ACTION_REQUIRED` if the system cannot match the alert to a transaction or cannot process the refund. {% endhint %} **Base URL:** `https://api.chargebackstop.com/v1/alerts/` **Authentication:** Bearer token via API key. Required abilities: * `alerts:read` for GET endpoints * `alerts:write` for PATCH endpoints **Access scope model:** * Organisation-level keys can access alerts for their own organisation only. * Admin partner-group keys can access alerts across all organisations for their partner. * Non-admin partner-group keys can access alerts only for organisations assigned to their group. *** ## GET /v1/alerts - list alerts Returns a paginated list of alerts accessible to the authenticated key. **API level:** Organisation-level and partner-level\ **Authentication:** `alerts:read` ### Query parameters | Parameter | Type | Description | | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | `status` | string | Filter by alert status: `ACTION_REQUIRED` (Ethoca only), `RESOLVED`, `INVALID` | | `organisation_id` | string | Filter by organisation ID | | `merchant_id` | string | Filter by merchant ID | | `alert_received_at_gte` | datetime | Include alerts received at or after this timestamp (ISO 8601, inclusive) | | `alert_received_at_lte` | datetime | Include alerts received at or before this timestamp (ISO 8601, inclusive) | | `sort` | string | Sort field: `-alert_received_at` (default), `alert_received_at`, `-action_required_deadline`, `action_required_deadline` | | `limit` | integer | Number of results per page | | `offset` | integer | Number of results to skip | ### Response codes | Code | Description | | ---- | ----------------------------------------------- | | 200 | Success | | 400 | Invalid request | | 401 | Unauthorised | | 403 | Forbidden — API key lacks `alerts:read` ability | | 422 | Validation error (e.g. invalid date range) | ### Important behaviour * If both `alert_received_at_gte` and `alert_received_at_lte` are sent, `alert_received_at_gte` must be less than or equal to `alert_received_at_lte`. * Default sort order is newest alert received first (`-alert_received_at`).
Example 1 request ```bash curl -X GET "https://api.chargebackstop.com/v1/alerts/?status=ACTION_REQUIRED&sort=-alert_received_at&limit=20&offset=0" \ -H "Authorization: Bearer " ```
Example 1 response ```json { "items": [ { "id": "netalrt_abc123", "alert_network_id": "1234567890", "organisation_id": "org_xyz456", "merchant_id": "mrch_abc123", "enrolment_id": "enrl_def456", "enrolment_type": "ETHOCA_ALERT", "status": "ACTION_REQUIRED", "chargeback_reason_code": "10.4", "transaction_amount_in_cents": 4999, "transaction_currency_code": "USD", "transaction_authorised_at": "2026-02-10T10:30:00Z", "action_required_deadline": "2026-02-17T10:30:00Z", "transaction_authorisation_code": "ABC123", "transaction_acquirer_reference_number": "74027012345678901234567", "transaction_statement_descriptor": "EXAMPLE STORE", "transaction_card_bin": "424242", "transaction_card_last4": "4242", "transaction_card_scheme": "VISA", "transaction_card_issuer": "Example Bank", "transaction_refund_outcome": null, "transaction_network_id": null, "subscription_cancel_outcome": null, "note": "Customer requested immediate review", "created_at": "2026-02-11T10:30:00Z", "updated_at": "2026-02-11T10:30:00Z", "integration_id": null, "integration_transaction_id": null, "links": [ { "rel": "self", "uri": "/v1/alerts/netalrt_abc123" } ] } ], "count": 1 } ```
*** ## GET /v1/alerts/{alert\_id} - get alert by ID Returns one alert if it is visible to the authenticated key. **API level:** Organisation-level and partner-level\ **Authentication:** `alerts:read` ### URL parameters | Parameter | Type | Description | | ---------- | ------ | ----------- | | `alert_id` | string | Alert ID | ### Response codes | Code | Description | | ---- | ----------------------------------------------- | | 200 | Success | | 400 | Invalid request | | 401 | Unauthorised | | 403 | Forbidden — API key lacks `alerts:read` ability | | 404 | Alert not found | ### Important behaviour * The same eligibility rules as list alerts apply. * Non-existent alerts return `404 Not found`.
Example 2 request ```bash curl -X GET "https://api.chargebackstop.com/v1/alerts/netalrt_abc123" \ -H "Authorization: Bearer " ```
Example 2 response ```json { "id": "netalrt_abc123", "alert_network_id": "1234567890", "organisation_id": "org_xyz456", "merchant_id": "mrch_abc123", "enrolment_id": "enrl_def456", "enrolment_type": "ETHOCA_ALERT", "status": "ACTION_REQUIRED", "chargeback_reason_code": "10.4", "transaction_amount_in_cents": 4999, "transaction_currency_code": "USD", "transaction_authorised_at": "2026-02-10T10:30:00Z", "action_required_deadline": "2026-02-17T10:30:00Z", "transaction_authorisation_code": "ABC123", "transaction_acquirer_reference_number": "74027012345678901234567", "transaction_statement_descriptor": "EXAMPLE STORE", "transaction_card_bin": "424242", "transaction_card_last4": "4242", "transaction_card_scheme": "VISA", "transaction_card_issuer": "Example Bank", "transaction_refund_outcome": null, "transaction_network_id": null, "subscription_cancel_outcome": null, "note": "Customer requested immediate review", "created_at": "2026-02-11T10:30:00Z", "updated_at": "2026-02-11T10:30:00Z", "integration_id": null, "integration_transaction_id": null, "links": [ { "rel": "self", "uri": "/v1/alerts/netalrt_abc123" } ] } ```
*** ## PATCH /v1/alerts/{alert\_id} - update alert Updates the alert note and/or actions the alert. **API level:** Organisation-level and partner-level\ **Authentication:** `alerts:write` ### URL parameters | Parameter | Type | Description | | ---------- | ------ | ------------------ | | `alert_id` | string | Alert ID to update | ### Request body All fields are optional. | Field | Type | Required | Description | | -------- | ------ | -------- | -------------------------------------------------------------------------- | | `action` | string | No | Action to apply: `REFUND`, `CANCEL`, `REFUND_AND_CANCEL`, `ACCEPT_DISPUTE` | | `note` | string | No | Customer-facing note saved on the alert | ### Response codes | Code | Description | | ---- | -------------------------------------------------------------- | | 200 | Success | | 400 | Invalid request | | 401 | Unauthorised | | 403 | Forbidden — API key lacks `alerts:write` ability | | 404 | Alert not found | | 422 | Validation error (e.g. invalid action, alert already resolved) | ### Important behaviour * This endpoint applies to Ethoca alerts only. Verifi RDR alerts are resolved automatically and cannot be actioned. * If `note` is provided, it is saved on the alert. * If `action` is omitted, only the note is updated. * Once an alert is in `RESOLVED`, it cannot be actioned again. * Action values map to available underlying actions at runtime. For detailed behaviour, see [Actioning alerts](/developer/partner-integration-guide/api-integration-guide.md): * `REFUND` prioritises refund actions. * `CANCEL` prioritises cancel/dismiss actions. * `REFUND_AND_CANCEL` prioritises combined refund-and-cancel, then refund-only if combined action is unavailable. * `ACCEPT_DISPUTE` maps to dismissing the alert.
Example 3 request ```bash curl -X PATCH "https://api.chargebackstop.com/v1/alerts/netalrt_abc123" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "action": "ACCEPT_DISPUTE", "note": "We decided to accept this dispute" }' ```
Example 3 response ```json { "id": "netalrt_abc123", "alert_network_id": "1234567890", "organisation_id": "org_xyz456", "merchant_id": "mrch_abc123", "enrolment_id": "enrl_def456", "enrolment_type": "ETHOCA_ALERT", "status": "RESOLVED", "chargeback_reason_code": "10.4", "transaction_amount_in_cents": 4999, "transaction_currency_code": "USD", "transaction_authorised_at": "2026-02-10T10:30:00Z", "action_required_deadline": "2026-02-17T10:30:00Z", "transaction_authorisation_code": "ABC123", "transaction_acquirer_reference_number": "74027012345678901234567", "transaction_statement_descriptor": "EXAMPLE STORE", "transaction_card_bin": "424242", "transaction_card_last4": "4242", "transaction_card_scheme": "VISA", "transaction_card_issuer": "Example Bank", "transaction_refund_outcome": "NOT_REFUNDED", "transaction_network_id": null, "subscription_cancel_outcome": null, "note": "We decided to accept this dispute", "created_at": "2026-02-11T10:30:00Z", "updated_at": "2026-02-11T10:32:00Z", "integration_id": null, "integration_transaction_id": null, "links": [ { "rel": "self", "uri": "/v1/alerts/netalrt_abc123" } ] } ```
*** ## Common error responses Error responses use this shape: ```json { "errors": [ { "code": "ERROR_CODE", "message": "Human-readable message" } ] } ```
Example 4: 401 Unauthorised Returned for invalid, expired, or missing API keys. ```json { "errors": [ { "code": "UNAUTHORISED", "message": "Unauthorised" } ] } ```
Example 5: 403 Forbidden Returned when the API key is valid but missing required ability. ```json { "errors": [ { "code": "FORBIDDEN", "message": "Forbidden" } ] } ```
Example 6: 404 Not found Returned when the alert is not found or not accessible. ```json { "errors": [ { "code": "NOT_FOUND", "message": "Not found" } ] } ```
Example 7: 422 Unprocessable Entity (invalid date range) Returned when `alert_received_at_gte` is greater than `alert_received_at_lte`. ```json { "errors": [ { "code": "INVALID_DATE_RANGE", "message": "alert_received_at_gte cannot be greater than alert_received_at_lte" } ] } ```
Example 8: 422 Unprocessable Entity (invalid enum value) Returned when `action` is not one of the supported values. ```json { "errors": [ { "code": "VALIDATION_ENUM", "message": "Validation error at ('body', 'update', 'action'). Input should be 'REFUND', 'CANCEL', 'REFUND_AND_CANCEL' or 'ACCEPT_DISPUTE'." } ] } ```
Example 9: 422 Unprocessable Entity (resolved alert cannot be actioned) ```json { "errors": [ { "code": "INVALID_ACTION", "message": "Failed to update netalrt_abc123 alert. This alert is in RESOLVED status and cannot be actioned." } ] } ```
Example 10: 422 Unprocessable Entity (no available action) Returned when the requested action cannot be mapped to any available action for the alert. ```json { "errors": [ { "code": "INVALID_ACTION", "message": "Failed to update netalrt_abc123 alert. No available action found." } ] } ```
Example 11: 422 Unprocessable Entity (action execution failed) Returned when the underlying action execution is rejected. ```json { "errors": [ { "code": "ACTION_FAILED", "message": "Failed to update netalrt_abc123 alert. The requested action is not allowed." } ] } ```
Additional reference: 500 Server error Unexpected server-side failures return: ```json { "errors": [ { "code": "SERVER_ERROR", "message": "Server error" } ] } ```
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.chargebackstop.com/developer/api-documentation/alerts.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.