---
title: "Reverse an event's awards"
method: POST
path: "/v1/events/{event_id}/reverse"
tags: ["Events"]
---

# Reverse an event's awards

`POST /v1/events/{event_id}/reverse`

## Request

- Base URL: `https://api.scrip.dev`
- URL: `https://api.scrip.dev/v1/events/{event_id}/reverse`
- Auth: HTTP bearer

Reverse rewards credited by a completed event's rules.

## Path parameters

- `event_id` string, uuid, required

## Headers

- `Idempotency-Key` string

## Request body

- ReverseEventRequest: Reverses the awards an event issued, all of them or a fraction.
  - `fraction` string: Fraction of each original award to reverse, as a decimal string greater than 0 and at most 1. Each award's share is rounded half up to the asset's scale. Omit to reverse all remaining value.
  - `idempotency_key` string, required: Your key for this reversal. Send it here or in the Idempotency-Key header. The same key returns the first reversal again; the same key with different fields is rejected.
  - `reason` string: Optional context recorded on the reversal and its ledger entries.
  - `shortfall_policy` 'report': What Scrip does when a participant has already spent part of an award. Defaults to `report`.

## Response `201`

Reversal created

- EventReversalResponse: The result of reversing the awards an event issued, with the amount recovered for each original award.
  - `created_at` string, date-time: When the reversal was created.
  - `event_id` string, uuid: The event whose awards were reversed.
  - `fraction` string: The fraction you sent, with 18 decimal places, such as `0.500000000000000000`. It is absent for a full reversal.
  - `id` string, uuid: The id of the reversal. Use it to find the reversal again.
  - `idempotency_key` string: The key you sent for this reversal.
  - `ineligible_entries` IneligibleEntryResponse[]: CREDIT entries of the event this reversal did not process, with reasons
    - `journal_entry_id` string, uuid: The journal entry that could not be reversed.
    - `reason` string: Why the entry is not reversible: SETTLEMENT_SHAPED, COMPLEX_POSTINGS, SIMPLE_ASSET, or NO_ENTITY_DESTINATION
  - `lines` EventReversalLineResponse[]: Per original award line accounting
    - `asset_id` string, uuid: Asset of the award
    - `ledger_entity_id` string, uuid: Ledger entity that was originally credited
    - `original_amount` string: Amount the original award credited
    - `original_journal_entry_id` string, uuid: Journal entry of the original award
    - `recovered_amount` string: Amount actually recovered from value still traceable to the original award
    - `requested_amount` string: Amount this reversal asked to claw back from this line
    - `reversal_journal_entry_id` string, uuid: REVERSAL journal entry that debited the recovered value; absent when nothing was recovered
    - `shortfall_amount` string: Requested value that could not be recovered (spent, expired, transferred, or held)
  - `reason` string: Why you reversed the event.
  - `shortfall_policy` 'report': What Scrip does when a participant has already spent part of an award.
  - `state_changes` StateChangeResponse[]: The original event's state changes (counters, tags, attributes, tiers). Reversals never revert state automatically; send a compensating event if your program logic requires it.
    - `changed_at` string, date-time: When the change occurred (RFC 3339)
    - `entity_id` string, uuid: Public UUID of the affected entity
    - `entity_type` 'PARTICIPANT' | 'GROUP' | 'PROGRAM': Whose state changed: a participant, a group, or the program.
    - `key` string: The key that changed
    - `new_value` string: New value (null for deletes)
    - `old_value` string: Previous value (null for new keys)
    - `operation` 'SET' | 'DELETE' | 'AUTO_RESET': What happened to the key: a value was written, the key was removed, or a counter was reset to zero on its schedule.
    - `program_id` string, uuid: Program scope for tier changes
    - `rule_id` string, uuid: Rule that caused this change
    - `state_type` 'TAG' | 'COUNTER' | 'ATTRIBUTE' | 'TIER': Which kind of state changed.
  - `status` 'COMPLETED': The outcome of the reversal.

## Other responses

- `400`: Validation failed (code: validation_error | invalid_fraction | invalid_shortfall_policy)
- `401`: The API key is missing or not valid. See [Authentication](https://docs.scrip.dev/authentication).
- `403`: The caller is not allowed to do this.
- `404`: Event not found (code: event_not_found)
- `409`: Request exceeds remaining reversible value, event not reversible, or idempotency conflict (code: already_reversed | event_not_reversible | reversal_exceeds_remaining | idempotency_conflict | retryable_conflict)
- `422`: The event has no reversible award entries or the fraction rounds to zero (code: nothing_reversible | fraction_rounds_to_zero)
- `429`: Too many requests. Wait the number of seconds in the `Retry-After` header, then retry. See [Limits and durations](https://docs.scrip.dev/limits#rate-limits).
- `500`: Something failed on Scrip's side. Retry the request, and quote `request_id` if it keeps failing. [Errors](https://docs.scrip.dev/errors) lists every code, and the [API introduction](https://docs.scrip.dev/api-reference/introduction) describes the error format.

---

[API](https://skmtc.dev/scrip/apis/scrip-api.md) · [All operations](https://skmtc.dev/scrip/apis/scrip-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scrip/apis/scrip-api/revisions/c52d35da8d97?raw)