Events

Reverse an event's awards

Reverse rewards credited by a completed event's rules.

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

Path parameters

event_idstring uuid required

The event's id.

Headers

Idempotency-Keystring

A key you choose to make this request safe to retry: 1 to 255 printable ASCII characters. Send the same key with the same request to get the first response again, marked Idempotent-Replayed: true. Routes that return a secret once, and claim links, do not replay a response. Event ingest uses the key as the event's identity.

Request body

fractionstring

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_keystring 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.

reasonstring

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.

Example request

{
  "fraction": "0.5",
  "idempotency_key": "refund-order-456-1",
  "reason": "partial refund",
  "shortfall_policy": "report"
}

Response

Reversal created

created_atstring date-time

When the reversal was created.

event_idstring uuid

The event whose awards were reversed.

fractionstring

The fraction you sent, with 18 decimal places, such as 0.500000000000000000. It is absent for a full reversal.

idstring uuid

The id of the reversal. Use it to find the reversal again.

idempotency_keystring

The key you sent for this reversal.

reasonstring

Why you reversed the event.

shortfall_policy'report'

What Scrip does when a participant has already spent part of an award.

status'COMPLETED'

The outcome of the reversal.

Example response

{
  "created_at": "2027-01-15T10:30:00Z",
  "event_id": "e5dc1b6a-7f3d-4e2a-8c1b-9a0f4d7e6c05",
  "fraction": "0.500000000000000000",
  "id": "9e3c5b71-6d28-4a94-8f1e-0c7b2a4d6e12",
  "idempotency_key": "refund-order-456-1",
  "ineligible_entries": [
    {
      "journal_entry_id": "657a0312-1aaa-4ba7-842b-edfbb39edf14",
      "reason": "SETTLEMENT_SHAPED"
    }
  ],
  "lines": [
    {
      "asset_id": "a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02",
      "ledger_entity_id": "5e7a9c13-2d4f-4b68-9a0c-e1b3d5f7a920",
      "original_amount": "54.25",
      "original_journal_entry_id": "657a0312-1aaa-4ba7-842b-edfbb39edf14",
      "recovered_amount": "27.13",
      "requested_amount": "27.13",
      "reversal_journal_entry_id": "657a0312-1aaa-4ba7-842b-edfbb39edf14",
      "shortfall_amount": "0"
    }
  ],
  "reason": "partial refund",
  "shortfall_policy": "report",
  "state_changes": [
    {
      "changed_at": "2027-01-15T10:30:00Z",
      "entity_id": "f7a8b9c0-1d2e-4f3a-b4c5-d6e7f8a9b006",
      "entity_type": "PARTICIPANT",
      "key": "lifetime_spend",
      "new_value": "575",
      "old_value": "500",
      "operation": "SET",
      "program_id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01",
      "rule_id": "c9f0f895-fb98-4b39-9f86-1e5a0d3e2b03",
      "state_type": "COUNTER"
    }
  ],
  "status": "COMPLETED"
}

Changes

No recorded changes to this operation across all 1 revision of this API.