Get Benefit

get

https://{Host}/v3/benefits/{loyaltyBenefitId}

Retrieve a single loyalty benefit by ID.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Get Benefit

Retrieves the details of a single loyalty benefit by its loyaltyBenefitId. By default, this returns the benefit's current published version. If a LIVE benefit has an edit in progress, the published version is still returned by default — pass status=DRAFT to retrieve the in-progress draft fork instead.

Example request

curl -X GET "https://eu.intouch.capillarytech.com/v3/benefits/86c29c3653f74c0a9f1b2c3d4e5f6a7b" \
  -H "Authorization: Basic <base64-encoded-credentials>"

curl -X GET "https://eu.intouch.capillarytech.com/v3/benefits/86c29c3653f74c0a9f1b2c3d4e5f6a7b?status=DRAFT" \
  -H "Authorization: Basic <base64-encoded-credentials>"

Prerequisites

Authentication: Basic auth or OAuth token with loyalty program read permissions.

Resource information

HTTP method	GET
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.

Query parameters

Field	Type	Required	Description
`status`	enum	Optional	Pass `DRAFT` to fetch the in-progress draft fork of a `LIVE` benefit. Omit this parameter to get the current published version. Supported values: `DRAFT`.

Example response

{
  "data": {
    "loyaltyBenefitId": "86c29c3653f74c0a9f1b2c3d4e5f6a7b",
    "version": 0,
    "metadata": {
      "name": "Birthday bonus",
      "description": "Extra points on birthday month",
      "programId": "973",
      "orgId": 12345,
      "expiryType": "CUSTOM",
      "status": "DRAFT",
      "customerEligibilityType": null,
      "benefitIdentifier": null,
      "loyaltyBenefitRecordId": null,
      "startDate": "2026-07-01T00:00:00+05:30",
      "endDate": "2026-12-31T23:59:59+05:30",
      "timezoneName": "Asia/Kolkata",
      "createdOn": "2026-06-23T14:32:24+05:30",
      "lastModifiedOn": "2026-06-23T14:32:24+05:30",
      "createdBy": 123456,
      "lastModifiedBy": 123456,
      "draftDetails": null
    },
    "benefitCategoryId": -1,
    "tierIds": [8159, 8165],
    "optin": {
      "basedOn": null,
      "audienceMapping": null,
      "activities": null,
      "restrictions": null,
      "optInStartDate": "2026-07-01T09:00:00+05:30",
      "optInEndDate": "2026-12-31T18:00: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": "6a3a4ba0c1d2e3f4a5b6c7d8"
  },
  "errors": null,
  "warnings": null
}

Response parameters

Field	Type	Description
`data`	object	Object containing the benefit.
`.loyaltyBenefitId`	string	Unique ID of the benefit.
`.version`	integer	Version number of the benefit. Increments on every update.
`.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. 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 it was sent in.
`..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. Contains the draft's `id`, `status`, `version`, `lastModifiedBy`, and `lastModifiedOn`. `null` when there's no draft in progress.
`.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`.
`..name`	string	Name of the activity. Returned only when a name is set.
`..event`	string	Event that triggers the activity.
`..expJSON`	string	JSON representation of the activity's rule expression. Returned only when a rule expression is set.
`..commonCycleActionMapping`	array	Cycle-to-action mappings for the activity. Returned only when cycles are configured.
`...cycle`	string	ID of the cycle this mapping applies to.
`...actions`	array	Actions that run when the target is achieved in this cycle.
`...startDate`	string	Indicates the cycle's start date and time 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-18T00:00:00+05:30` → 18 June 2026, 00:00:00 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
`...endDate`	string	Indicates the cycle's end date and time 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-07-30T23:59:59+05:30` → 30 July 2026, 23:59:59 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
`..milestones`	array	Milestone definitions for the activity. Returned only when milestones are configured.
`..allCycles`	array	Cycle entries computed for the activity.
`.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.
`..liabilityOwnerId`	integer	ID of the liability owner.
`..liabilityOwnerName`	string	Name of the liability owner.
`..liabilityOwnerType`	enum	Type of the liability owner. Possible values: `PARTNER`, `PROGRAM`.
`..componentType`	enum	Component the split applies to. Possible values: `PROGRAM`, `PROMOTION`, `BENEFITS`.
`..componentId`	integer	ID of the component the split applies to.
`..ratio`	number	Percentage share of the liability assigned to this owner.
`..orgId`	integer	Org ID of the liability owner entry.
`..createdBy`	integer	ID of the user who created the liability owner entry.
`..active`	boolean	Whether the liability owner entry is active.
`.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
`loyaltyBenefitId=<id>`	Error	No benefit matches the given `loyaltyBenefitId`. HTTP 404.

Note: This error returns 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.

Responses

200

Benefit record

401

Authentication failed

404

No benefit matches the given loyaltyBenefitId

Language

Credentials

Basic

base64

URL

Loading…

Response

Click Try It! to start a request and see the response here!