---
title: "Revoke a Loyalty Promotion"
method: POST
path: "/v3/promotions/revoke"
---

# Revoke a Loyalty Promotion

`POST /v3/promotions/revoke`

Revokes a customer's enrollment or opt-in from a v3 unified loyalty promotion.

## Query parameters

- `revokeAllEnrollments` boolean
- `revokeAllOptIns` boolean

## Headers

- `Authorization` string, required
- `Content-Type` string, required

## Request body

- object
  - `requestId` string — A plain string reference identifier for this revoke request. Each requestId must be unique per org — duplicate values are rejected.
  - `action` 'REVOKE_ENROLL' | 'REVOKE_OPTIN', required — The revoke action to perform. Case-sensitive.
  - `programId` integer, required — Unique identifier of the loyalty program.
  - `promotion` object, required — Identifies the promotion to revoke from. Provide exactly one of promotionId or promotionIdentifier.
    - `promotionId` integer — Numeric identifier of the promotion.
    - `promotionIdentifier` string — UUID string identifier of the promotion.
  - `customers` object[], required — List of customers to revoke. Exactly 1 entry is supported in the current release.
    - `identifierName` 'id' | 'mobile' | 'email' | 'externalId', required — Customer identifier type.
    - `identifierValue` string, required — Value for the customer identifier.
    - `source` 'FACEBOOK' | 'WEB_ENGAGE' | 'INSTORE' | 'MARTJACK' | 'TMALL' | 'TAOBAO' | 'JD' | 'ECOMMERCE' | 'WEBSITE' | 'LINE' | 'ALL' — Source of the customer's registration.
    - `enrollmentIds` integer[] — Enrollment IDs to revoke. Required for REVOKE_ENROLL unless revokeAllEnrollments=true. Max 10.
    - `optInIds` integer[] — Opt-in IDs to revoke. Required for REVOKE_OPTIN unless revokeAllOptIns=true. Max 10.
  - `optOutDate` string — ISO-8601 timestamp to retroactively stamp as the revoke date. Must not be in the future.
  - `storeUnitId` integer — Till ID to stamp on the event log for the revoke and any cascade. Falls back to the authenticated user's till when omitted.
  - `sourceDetails` object — Audit attribution for the revoke operation.
    - `source` string — Channel or system performing the revoke.
    - `sourceId` string — Workflow or correlation identifier.
    - `sourceActivity` string — Activity tag from the calling system.
    - `sourceMetadata` object — Free-form key-value audit metadata to associate with the revoke operation.
      - `revokedBy` integer — ID of the admin user performing the revoke.
      - `reason` string — Reason for the revoke.
      - `notes` string — Additional notes.

## Response `200`

Revoke processed. Check data.status and customerResults[].status for per-customer outcomes.

- object
  - `data` object
    - `requestId` string
    - `action` string
    - `status` 'SUCCESS' | 'FAILED' | 'PARTIAL_SUCCESS'
    - `promotionId` integer
    - `promotionIdentifier` string
    - `totalCount` integer
    - `failureCount` integer
    - `customerResults` object[]
      - `identifierName` string
      - `identifierValue` string
      - `customerId` integer
      - `revokedEnrollmentIds` integer[]
      - `revokedOptInIds` integer[]
      - `status` 'SUCCESS' | 'FAILED'
      - `errors` object[]
        - `code` integer
        - `message` string
      - `warnings` object[]
        - `message` string
  - `errors` object[], nullable
    - `code` integer
    - `message` string
  - `warnings` object[], nullable
    - `message` string

## Other responses

- `400` — Request-level validation failure.

---

[API](https://skmtc.net/capillarytech/apis/sample-api.md) · [All operations](https://skmtc.net/capillarytech/apis/sample-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/capillarytech/sample-api/revisions/de241f2ed9b3/schema)