Cancel a reward

Cancel a reward before your operator approves it, without erasing its history.

Cancellation stops a reward before your operator approves it. It restores authorized issuance capacity once and preserves the original reward and event history.

Endpoint#

POST /v1/rewards/{rewardId}/cancel
Authorization: Bearer <your-server-api-key>
Idempotency-Key: cancel_referral_0182
Content-Type: application/json

{
  "reason": "Partner eligibility correction before approval"
}

rewardId is the existing Slices reward ID. reason is required and must be 1–256 characters. Use a useful operational explanation without personal information. The idempotency key follows the same format as issuance keys and is supplied in the header.

TypeScript#

const cancelled = await slices.rewards.cancel("rwd_demo0001", {
  reason: "Partner eligibility correction before approval",
  idempotencyKey: "cancel_referral_0182",
});

console.log(cancelled.status); // "cancelled"

Response#

A successful cancellation returns 200 OK and the current reward:

{
  "data": {
    "id": "rwd_demo0001",
    "campaignId": "cmp_pilot001",
    "recipient": {
      "walletAddress": "0x0000000000000000000000000000000000001001",
      "verificationStatus": "unverified",
      "verificationUrl": null
    },
    "asset": {
      "chainId": 31337,
      "tokenAddress": "0x0000000000000000000000000000000000002001",
      "symbol": "TST",
      "decimals": 6
    },
    "amountBaseUnits": "1000000",
    "event": {
      "id": "referral_0182",
      "type": "referral.qualified"
    },
    "source": "partner_attested",
    "status": "cancelled",
    "statusReason": "Partner eligibility correction before approval",
    "payoutCampaignId": null,
    "deliveredAmountBaseUnits": "0",
    "deliveryEvidence": null,
    "createdAt": "2026-09-11T12:00:00Z",
    "updatedAt": "2026-09-11T12:05:00Z"
  }
}

All addresses, IDs, amounts, and timestamps in this example are synthetic. TST on chain 31337 is a local test profile, not an available production asset.

A repeated successful cancellation is harmless; capacity is not restored twice. Reuse the original cancellation key and reason when recovering an uncertain response. Reusing that key for different content can produce IDEMPOTENCY_CONFLICT.

The cancellation boundary#

Only an accepted or queued reward is eligible. Cancellation and the operator's approval use a single transactional decision: either cancellation wins and the grant leaves the draft campaign, or the approval wins and cancellation is rejected.

A reward already approved, sent, delivered, or failed returns 409 INVALID_STATE. A declined wallet request or a reverted transfer does not make an approved reward cancellable again: the operator can retry it, or close the draft campaign, which cancels its unsent transfers from their side.

The API does not implement refunds, clawbacks, edits, or a “force cancel” override.

Replacing a cancelled allocation#

The cancelled event remains deduplicated. Do not expect a new idempotency key to revive it. If your business policy authorizes a corrected allocation, create a deliberate new event identity and persist the connection to the original in your own audit records.

Do not issue the replacement until cancellation of the original is confirmed. A timeout is not a confirmed cancellation.

Pausing is different#

Pausing a campaign blocks new issuance. It does not cancel existing rewards, withdraw an approval, or recall tokens. Handle each eligible cancellation explicitly, then coordinate any sending hold with the operator.

Related: Reward states, Idempotency, and Funding and budgets.