Create Benefit

post

https://{Host}/v3/benefits

Create a new loyalty benefit in DRAFT status.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Create Benefit

Creates a new loyalty benefit in DRAFT status for a program. The benefit enters a maker-checker approval workflow: submit it with Submit Benefit for Approval and publish it with Approve or Reject Benefit before it goes live. A new benefit has no benefitIdentifier or loyaltyBenefitRecordId until it's approved.

Example request

curl -X POST "https://eu.intouch.capillarytech.com/v3/benefits" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Birthday bonus",
    "description": "Extra points on birthday month",
    "programId": "973",
    "expiryType": "CUSTOM",
    "startDate": "2026-07-01T00:00:00+05:30",
    "endDate": "2026-12-31T23:59:59+05:30",
    "timezoneName": "Asia/Kolkata",
    "tierIds": [8159, 8165],
    "optin": {
      "optInStartDate": "2026-07-01T09:00:00+05:30",
      "optInEndDate": "2026-12-31T18:00:00+05:30"
    },
    "activities": [
      { "type": "SINGLE", "event": "TransactionAdd" }
    ]
  }'

Prerequisites

Authentication: Basic auth or OAuth token with loyalty program management permissions.
The tiers listed in tierIds must exist in the program.

Resource information

HTTP method	POST
Authentication	Basic or OAuth
Pagination supported?	NO
Rate limit	YES
Batch support	NO

Body parameters

API Quick Reference

Benefit
├── name (string)
├── description (string)
├── programId (string)
├── expiryType (enum)
├── startDate (string)
├── endDate (string)
├── timezoneName (string)
├── tierIds[] (integer)
├── optin
│   ├── optInStartDate (string)
│   └── optInEndDate (string)
└── activities[]
    ├── type (enum)
    └── event (string)

Field	Type	Required	Description
`name`	string	Required	Display name of the benefit. Max 255 characters.
`description`	string	Required	Description of the benefit. Max 1000 characters.
`programId`	string	Required	Loyalty program ID the benefit belongs to, passed as a string (for example, `"973"`). To retrieve the `programId`, use the Get Loyalty Programs API.
`expiryType`	enum	Required	How the benefit's validity ends. Case-sensitive. `CUSTOM` requires `endDate`. `INDEFINITE` sets a far-future end date automatically. Supported values: `CUSTOM`, `INDEFINITE`.
`startDate`	string	Required	Defines the benefit's start date and time in ISO 8601 format with the region offset. For example: The start date is at 14:30:45 on December 16, 2025, in India Format for the request parameter: `2025-12-16T14:30:45+05:30` Returned unchanged in the response, in the offset you send.
`endDate`	string	Conditional	Defines the benefit's end date and time in ISO 8601 format with the region offset. For example: The end date is at 14:30:45 on December 16, 2025, in India Format for the request parameter: `2025-12-16T14:30:45+05:30` Required when `expiryType` is `CUSTOM`. Omit it for `INDEFINITE`.
`timezoneName`	string	Required	IANA time zone name for the benefit (for example, `Asia/Kolkata`). Use `timezoneName` (lowercase `z`) — this is the correct field name across Capillary APIs.
`tierIds`	array (integer)	Required	Tier IDs the benefit applies to. Each tier must exist in the program. Retrieve tier IDs with the List All Tiers API.
`optin`	object	Optional	Object containing the opt-in window during which customers can opt in to the benefit.
`.optInStartDate`	string	Optional	Defines the opt-in window's start date and time in ISO 8601 format with the region offset. For example: The start date is at 14:30:45 on December 16, 2025, in India Format for the request parameter: `2025-12-16T14:30:45+05:30`
`.optInEndDate`	string	Optional	Defines the opt-in window's end date and time in ISO 8601 format with the region offset. For example: The end date is at 14:30:45 on December 16, 2025, in India Format for the request parameter: `2025-12-16T14:30:45+05:30`
`activities`	array (object)	Required	Activities that the benefit applies to.
`.type`	enum	Required	Activity type. Case-sensitive. Supported values: `SINGLE`.
`.event`	string	Required	Event that triggers the activity (for example, `TransactionAdd`).

Example response

{
  "data": {
    "loyaltyBenefitId": "a70ae03d0f54486fa9c3f4e8d89ce6e5",
    "version": 0,
    "metadata": {
      "name": "Birthday bonus",
      "description": "Extra points on birthday month",
      "programId": "2352",
      "orgId": "973",
      "expiryType": "CUSTOM",
      "status": "DRAFT",
      "customerEligibilityType": null,
      "benefitIdentifier": null,
      "loyaltyBenefitRecordId": null,
      "startDate": "2026-07-01T11:30:00+05:30",
      "endDate": "2027-01-01T11:29:59+05:30",
      "timezoneName": "Asia/Kolkata",
      "createdOn": "2026-06-23T15:08:08+05:30",
      "lastModifiedOn": "2026-06-23T15:08:08+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-07-01T20:30:00+05:30",
      "optInEndDate": "2027-01-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": null,
    "id": "6a3a54007960e562c3e7c1c3"
  },
  "errors": null,
  "warnings": null
}

Response parameters

Field	Type	Description
`data`	object	Object containing the created benefit.
`.loyaltyBenefitId`	string	Unique ID assigned to the benefit. Use it with Get Benefit, Update Benefit, and the workflow endpoints.
`.version`	integer	Version number of the benefit. `0` for a new draft.
`.metadata`	object	Object containing the benefit's core attributes and audit details.
`..name`	string	Display name of the benefit.
`..description`	string	Description of the benefit.
`..programId`	string	Loyalty program ID the benefit belongs to.
`..orgId`	integer	Org ID derived from the auth token.
`..expiryType`	enum	How the benefit's validity ends. Possible values: `CUSTOM`, `INDEFINITE`.
`..status`	enum	Current stage of the benefit lifecycle. Always `DRAFT` on creation. Possible values: `DRAFT`, `PENDING_APPROVAL`, `LIVE`, `UPCOMING`, `PAUSED`, `STOPPED`.
`..customerEligibilityType`	string	Customer eligibility configuration. `null` unless advanced eligibility is set up.
`..benefitIdentifier`	string	Identifier assigned when the benefit is approved. `null` while the benefit is in `DRAFT` or `PENDING_APPROVAL`.
`..loyaltyBenefitRecordId`	integer	Record ID assigned when the benefit is approved. `null` while the benefit is in `DRAFT` or `PENDING_APPROVAL`.
`..startDate`	string	Date and time when the benefit starts, in ISO 8601 format. Returned in the offset you sent.
`..endDate`	string	Date and time when the benefit ends, in ISO 8601 format. For `INDEFINITE` benefits, set to a far-future date automatically.
`..timezoneName`	string	IANA time zone name, as sent.
`..createdOn`	timestamp	Indicates the date and time the benefit was created, in ISO 8601 format, returned in the server time zone. EU server example: `2025-12-16T14:30:45Z` → 16 December 2025, 14:30:45 (UTC) India server example (real capture from this environment): `2026-06-23T14:32:24+05:30` → 23 June 2026, 14:32:24 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
`..lastModifiedOn`	timestamp	Indicates the date and time the benefit was last modified, in ISO 8601 format, returned in the server time zone. EU server example: `2025-12-16T14:30:45Z` → 16 December 2025, 14:30:45 (UTC) India server example (real capture from this environment): `2026-06-23T14:32:24+05:30` → 23 June 2026, 14:32:24 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
`..createdBy`	integer	Till ID of the person who created the benefit. Retrieve till IDs with the Get Active Tills API.
`..lastModifiedBy`	integer	Till ID of the person who last modified the benefit. Retrieve till IDs with the Get Active Tills API.
`..draftDetails`	object	Object containing details of an in-progress draft when a live benefit has an edit underway. `null` on a new draft.
`.benefitCategoryId`	integer	Benefit category ID. `-1` means no benefit category is assigned.
`.tierIds`	array	Tier IDs the benefit applies to.
`.optin`	object	Object containing the opt-in window, as sent. `null` if no opt-in window was configured.
`..basedOn`	string	Opt-in basis. `null` unless configured.
`..audienceMapping`	object	Object containing the opt-in's audience mapping. `null` unless configured.
`..activities`	array	Activities scoped to the opt-in. `null` unless configured.
`..restrictions`	object	Object containing the opt-in's restrictions. `null` unless configured.
`..optInStartDate`	string	Date and time when the opt-in window opens, in ISO 8601 format.
`..optInEndDate`	string	Date and time when the opt-in window closes, in ISO 8601 format.
`.activities`	array	Activities the benefit applies to.
`..type`	enum	Activity type. Possible values: `SINGLE`.
`..event`	string	Event that triggers the activity.
`..allCycles`	array	Cycle entries computed for the activity. Empty on a new draft.
`.limits`	array	Usage limits configured for the benefit. `null` or empty unless limits are configured.
`.configAttributes`	object	Object containing advanced configuration attributes. `null` unless configured.
`.liabilityOwnerSplitInfo`	array	Liability split configuration entries. Each entry defines how liability for the benefit is split. `null` unless configured. See Get Benefit for entry fields.
`.workflowMetadata`	object	Object containing additional workflow data. `null` unless configured.
`.communicationApprovalStatus`	object	Object containing the communication approval result. `null` until the benefit is approved.
`.parentId`	string	ID of the parent benefit, when this benefit is a draft fork of a live benefit. `null` otherwise.
`.parentDetails`	object	Object containing details of the parent benefit. `null` otherwise.
`.comments`	string	Reviewer's note from the most recent workflow action. `null` until reviewed.
`.id`	string	Unique ID of this benefit record.
`errors`	array	Error list. `null` on success.
`warnings`	array	Warning list. `null` on success.

Error & warning codes

Code	Type	Description
`LOYALTY_BENEFITS.NAME_REQUIRED`	Error	`name` is missing. HTTP 400.
`LOYALTY_BENEFITS.DESCRIPTION_REQUIRED`	Error	`description` is missing. HTTP 400.
`LOYALTY_BENEFITS.PROGRAM_ID_REQUIRED`	Error	`programId` is missing. HTTP 400.
`LOYALTY_BENEFITS.END_DATE_REQUIRED_FOR_CUSTOM`	Error	`expiryType` is `CUSTOM` but `endDate` is missing. HTTP 400.
`INVALID_EXPIRYTYPE`	Error	`expiryType` is not `INDEFINITE` or `CUSTOM`. HTTP 400.
`LOYALTY_BENEFITS.TIER_NOT_FOUND`	Error	One or more IDs in `tierIds` don't exist in the program. HTTP 400.
`Invalid input`	Error	An `activities[].type` value is not `SINGLE`. HTTP 400.

Note: Validation errors return a generic numeric code on the wire rather than an error-specific number. The Code column shows the stable symbolic code or message text carried in the error.

Body Params

name

string

required

Display name of the benefit.

description

string

required

Description of the benefit.

programId

string

required

Loyalty program ID the benefit belongs to.

expiryType

string

enum

required

How the benefit's validity ends.

Allowed:

startDate

string

required

Defines the benefit's start date and time in ISO 8601 format with the region offset (for example, 2025-12-16T14:30:45+05:30). Returned unchanged in the response, in the offset you send.

endDate

string

Defines the benefit's end date and time in ISO 8601 format with the region offset (for example, 2025-12-16T14:30:45+05:30). Required when expiryType is CUSTOM.

timezoneName

string

required

IANA time zone name.

tierIds

array of integers

required

Tier IDs the benefit applies to.

tierIds*

optin

object

activities

array of objects

required

activities*

Headers

X-CAP-API-OAUTH-TOKEN

string

Responses

201

Benefit created in DRAFT status

400

Validation error: see the error table in the doc page

401

Authentication failed

Language

Credentials

Basic

base64

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

Create Benefit

Example request

Prerequisites

Resource information

Body parameters

API Quick Reference

Example response

Response parameters

Error & warning codes

200OK