This API revokes cart promotions that a customer has earned but not yet redeemed.

When you revoke an earned promotion, the system removes the customer's entitlement to redeem that promotion. The promotion is no longer available to the customer for future transactions.
Use this API to cancel a promotion issued in error, or when a customer returns a qualifying purchase that originally triggered the promotion earn.
You can revoke multiple promotions for a single customer in one request by including multiple entries in the earnRevokeDetails array.
Only unredeemed promotions can be revoked. You cannot revoke a promotion that has already been redeemed.

Example request

curl --location 'https://{Host}/api_gateway/v1/promotions/revokeEarn' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
--data '
{
  "customerId": 566881933,
  "earnRevokeDetails": [
    {
      "promotionId": "69117663b1cfc114606fd7fb",
      "earnIds": [
        "6911eaf1f57b486147effac0"
      ]
    },
    {
      "promotionId": "69058646b1cfc114606f7bbe",
      "earnIds": [
        "68f869d94a314550c4b46047"
      ]
    }
  ]
}
'

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions/revokeEarn' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmJ1a2w6NzYMGQ3YzI4ZjU4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=cc8Wgks3OrtzAV5WVi0XvYs2zw.tj0w-1762861404837-0.0.1.1-604800000' \
--data '
{
  "customerId": 566881933,
  "earnRevokeDetails": [
    {
      "promotionId": "68f9f2904a314550c4b46dc0",
      "earnIds": [
        "string"
      ]
    }
  ]
}
'

Prerequisites

Authentication: Basic or OAuth authentication.
Default access group

Resource information


Pagination	No
Batch support	No

Request body parameters

Field	Type	Required	Description
customerId	Number	Yes	Specifies the unique identifier for the customer.
earnRevokeDetails	Array	Yes	Defines a list of cart promotion and earn ID details to be revoked.
..promotionId	String	Yes	Specifies the unique identifier of the cart promotion.
..earnIds	Array	Yes	Defines a list of specific earn transaction IDs to be revoked. Maximum earnIds supported in a single request : 1000 Example : "earnIds": [ "earned_id_1A2B3C", "earned_id_4D5E6F", "earned_id_7G8H9I" ]

Example response

{
    "data": {
        "customerId": 566881933,
        "revokedDetails": [
          {
            "promotionId": "69117663b1cfc114606fd7fb",
            "revokedEarnIds": [
              "6911eaf1f57b486147effac0"
            ],
            "status": "SUCCESS"
          },
          {
            "promotionId": "69058646b1cfc114606f7bbe",
            "revokedEarnIds": [
              "68f869d94a314550c4b46047"
            ],
            "status": "SUCCESS"
          }
    T   ]
    },
    "errors": []
}

Response parameters

Field	Type	Description
data	Object	Indicates the result of the revocation attempt.
..customerId	Number	Indicates customer ID for whom the revocation was processed.
..revokedDetails	Array	Specifies a list of objects detailing the outcome for each cart promotion.
....promotionId	String	Indicates the cart promotion ID for this specific revocation result.
....revokedEarnIds	Array	Indicates a list of earn IDs that were successfully revoked.
....status	String	Indicates status of the revocation.
errors	Array	Specifies a list of errors, if any, encountered during the request.
..code	Number	Indicates the error code.
..message	String	Specifies a descriptive error message.

Error codes

Code	Description
400	Invalid request. Check required parameters. Ensure all required parameters (such as earn ID, promotion ID) are provided and valid.
404	Promotion, Earn, or Customer not found. Use a valid and existing promotion, earn, or customer identifier.
729	Promotion earn instance already redeemed. Cannot revoke; provide a valid, unredeemed earn instance.
730	Earn revoke not possible for POS and CODE promotion. Only supported earn types can be revoked.
731	Earn ID passed is not valid. Use a valid earn ID.
500	Internal server error. Retry the request after a short delay, and contact support if the error persists.

200200

400400