patch
https://{Host}/v3/benefits//status
Submit a DRAFT benefit for approval.
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
Submit Benefit for Approval
Submits a DRAFT benefit for approval, transitioning it from DRAFT to PENDING_APPROVAL. A reviewer then publishes or rejects it with Approve or Reject Benefit.
This endpoint shares the path PATCH /v3/benefits/{loyaltyBenefitId}/status with the lifecycle actions in Manage Benefit Status. Set action to SUBMIT_FOR_APPROVAL to submit a draft.
Example request
curl -L -g -X PATCH 'https://eu.api.capillarytech.com/v3/benefits/{{loyaltyBenefitId}}/status' \
-H 'Content-Type: application/json' \
-H 'Authorization: {{auth}}' \
-H 'X-CAP-API-AUTH-ORG-ID: {{orgId}}' \
-d '{
"action": "SUBMIT_FOR_APPROVAL",
"comment": "SUbmitting the benefit for approval",
"submittedBy": {{tillId}},
"lastUpdatedBy": {{tillId}}
}'Prerequisites
- Authentication: Basic auth or OAuth token with loyalty program management permissions.
- The benefit must be in
DRAFTstatus.
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 to submit, returned by Create Benefit. |
Body parameters
| Field | Type | Required | Description |
|---|---|---|---|
action | enum | Required | Lifecycle action to perform. Set to SUBMIT_FOR_APPROVAL to submit a draft for approval. Case-sensitive. Supported values: SUBMIT_FOR_APPROVAL. |
comment | string | Optional | Note recorded with the submission. Max 150 characters. Returned as comments in the response. |
submittedBy | integer | Optional | Till ID of the person submitting the benefit. Retrieve till IDs with the Get Active Tills API. |
lastUpdatedBy | integer | Required | Till ID of the person performing the action. Retrieve till IDs with the Get Active Tills API. |
Example response
{
"data": {
"loyaltyBenefitId": "a70ae03d0f54486fa9c3f4e8d89ce6e5",
"version": 2,
"metadata": {
"name": "Birthday bonus",
"description": "Extra points on birthday month",
"programId": "2352",
"orgId": 50947,
"expiryType": "CUSTOM",
"status": "PENDING_APPROVAL",
"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:08:40+05:30",
"createdBy": 50821171,
"lastModifiedBy": 50821171,
"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
}Response parameters
| Field | Type | Description |
|---|---|---|
data | object | Object containing the benefit after submission. Has the same fields as the Get Benefit response. |
.metadata | object | Object containing workflow stage data. |
..status | enum | Stage after the action. Always PENDING_APPROVAL after a successful submission. Possible values: DRAFT, PENDING_APPROVAL, LIVE, UPCOMING, PAUSED, STOPPED. |
.comments | string | Note recorded with the submission, echoed from the comment field in the request. |
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> → PENDING_APPROVAL | Error | The benefit is not in a status from which it can be submitted. The message names the attempted transition. 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