patch
https://{Host}/v3/benefits//status
Pause, resume, stop, or revoke a benefit.
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
Manage Benefit Status
Changes the lifecycle status of a benefit by performing a status action. This endpoint uses the path PATCH /v3/benefits/{loyaltyBenefitId}/status and covers the PAUSE, RESUME, STOP, and REVOKE actions.
To submit a draft for approval, use the same endpoint with action set to SUBMIT_FOR_APPROVAL, documented separately at Submit Benefit for Approval.
Lifecycle transitions
Each action moves the benefit between statuses:
| Action | From status | To status | Effect |
|---|---|---|---|
PAUSE | LIVE, UPCOMING | PAUSED | Temporarily stops the benefit from applying. |
RESUME | PAUSED | LIVE or UPCOMING | Reactivates a paused benefit. It returns to LIVE if its start date has passed, or UPCOMING if the start date is still in the future. |
STOP | LIVE, UPCOMING, PAUSED | STOPPED | Permanently ends the benefit. A stopped benefit can't be resumed. |
REVOKE | PENDING_APPROVAL | DRAFT | Withdraws a benefit awaiting approval and returns it to DRAFT for further edits. |
A benefit can only move along a valid transition. Applying an action from a status that doesn't allow it returns an error (HTTP 422).
Example request
curl -L -X PATCH 'https://nightly.api.capillarytech.com/v3/benefits/05da702a7eae468185835f5a74db54f6/status' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic RmOTJiOGQwMGM2ZmY5ZWMxNGEyYjE2YWNiYTg2MzA=' \
-H 'X-CAP-API-AUTH-ORG-ID: 100737' \
-d '{
"action": "PAUSE",
"lastUpdatedBy": 50685425
}'Prerequisites
- Authentication: Basic auth or OAuth token with loyalty program management permissions.
- The benefit must be in a status that allows the action you're performing. See Lifecycle transitions.
Resource information
| HTTP method | PATCH |
|---|---|
| Authentication | Basic or OAuth |
| Pagination supported? | NO |
| Rate limit | YES |
| Batch support | NO |
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
loyaltyBenefitId | string | Required | Unique ID of the benefit, returned by Create Benefit. |
Body parameters
| Field | Type | Required | Description |
|---|---|---|---|
action | enum | Required | Lifecycle action to perform. Case-sensitive. Supported values: PAUSE: temporarily stops the benefit from applying, RESUME: reactivates a paused benefit — returns to LIVE if the start date has passed, or UPCOMING if it's still in the future, STOP: permanently ends the benefit; can't be resumed, REVOKE: withdraws a benefit awaiting approval and returns it to DRAFT for further edits. See Lifecycle transitions for the full set of valid from/to status pairs. |
lastUpdatedBy | integer | Required | Till ID of the person performing the action. Retrieve till IDs with the Get Active Tills API. |
Example response
The Paused tab shows the response to a PAUSE action. The Stopped tab shows the response to a STOP action, which is terminal — a stopped benefit can't be resumed. Both examples show comments retaining the note from the most recent workflow action — here, the earlier approval — rather than being cleared on each subsequent action.
{
"data": {
"loyaltyBenefitId": "a70ae03d0f54486fa9c3f4e8d89ce6e5",
"version": 7,
"metadata": {
"name": "Birthday bonus",
"description": "Extra points on birthday month",
"programId": "2352",
"orgId": 50947,
"expiryType": "CUSTOM",
"status": "PAUSED",
"customerEligibilityType": null,
"benefitIdentifier": null,
"loyaltyBenefitRecordId": null,
"startDate": "2026-08-01T11:30:00+05:30",
"endDate": "2027-02-01T11:29:59+05:30",
"timezoneName": "Asia/Kolkata",
"createdOn": "2026-06-23T15:08:08+05:30",
"lastModifiedOn": "2026-06-23T15:29:07+05:30",
"createdBy": 50821171,
"lastModifiedBy": 50685425,
"draftDetails": null
},
"benefitCategoryId": -1,
"tierIds": [
8159,
8165,
8166,
10545,
10656
],
"optin": {
"basedOn": null,
"audienceMapping": null,
"activities": null,
"restrictions": null,
"optInStartDate": "2026-08-01T20:30:00+05:30",
"optInEndDate": "2027-02-01T05:30:00+05:30"
},
"activities": [
{
"type": "SINGLE",
"event": "TransactionAdd",
"allCycles": []
}
],
"limits": null,
"configAttributes": null,
"liabilityOwnerSplitInfo": null,
"workflowMetadata": null,
"communicationApprovalStatus": null,
"parentId": null,
"parentDetails": null,
"comments": "TZ audit test submission",
"id": "6a3a54007960e562c3e7c1c3"
},
"errors": null,
"warnings": null
}{
"data": {
"loyaltyBenefitId": "86c29c3653f74c0a9f1b2c3d4e5f6a7b",
"version": 9,
"metadata": {
"name": "Birthday bonus",
"description": "Extra points on birthday month",
"programId": "973",
"orgId": 12345,
"expiryType": "CUSTOM",
"status": "STOPPED",
"customerEligibilityType": null,
"benefitIdentifier": "5e9f6a2b-1c3d-4e5f-8a7b-9c1d2e3f4a5b",
"loyaltyBenefitRecordId": 287,
"startDate": "2026-08-01T00:00:00+05:30",
"endDate": "2027-01-31T23:59:59+05:30",
"timezoneName": "Asia/Kolkata",
"createdOn": "2026-06-23T14:32:24+05:30",
"lastModifiedOn": "2026-06-23T14:42:10+05:30",
"createdBy": 123456,
"lastModifiedBy": 123456,
"draftDetails": null
},
"benefitCategoryId": -1,
"tierIds": [
8159,
8165
],
"optin": {
"basedOn": null,
"audienceMapping": null,
"activities": null,
"restrictions": null,
"optInStartDate": "2026-08-01T09:00:00+05:30",
"optInEndDate": "2027-01-31T18:00:00+05:30"
},
"activities": [
{
"type": "SINGLE",
"event": "TransactionAdd",
"allCycles": []
}
],
"limits": null,
"configAttributes": null,
"liabilityOwnerSplitInfo": null,
"workflowMetadata": null,
"communicationApprovalStatus": {
"success": true,
"message": "No communications to approve",
"response": null,
"statusCode": 200
},
"parentId": null,
"parentDetails": null,
"comments": "Approved for launch",
"id": "6a3a4ba0c1d2e3f4a5b6c7d8"
},
"errors": null,
"warnings": null
}Response parameters
| Field | Type | Description |
|---|---|---|
data | object | Object containing the benefit after the action. Has the same fields as the Get Benefit response. |
.metadata | object | Object containing workflow stage data. |
..status | enum | Stage after the action. Possible values: DRAFT, PENDING_APPROVAL, LIVE, UPCOMING, PAUSED, STOPPED. |
errors | array | Error list. null on success. |
warnings | array | Warning list. null on success. |
Error & warning codes
| Code | Type | Description |
|---|---|---|
loyaltyBenefitId=<id> | Error | No benefit matches the given loyaltyBenefitId. HTTP 404. |
<current> → <target> | Error | The action isn't allowed from the benefit's current status. The message names the attempted transition (for example, DRAFT → PAUSED). HTTP 422. |
Note: These errors return a generic numeric code on the wire rather than an error-specific number. The Code column shows the identifying text carried in the error message.
Authentication failed
No benefit matches the given loyaltyBenefitId
Illegal status transition