Time	Status	User Agent
Retrieving recent requests…

The Earn Cart Promotion API enables the immediate granting of cart promotions to specific customers. This direct earning capability means cart promotions can be associated with a customer's cart and made available for redemption subject to defined conditions directly through a transaction or other activity. This allows redemption without the need for prior evaluation, which streamlines the cart promotion awarding process.

Example request

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions/68f869d94a314550c4b46047/earn' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmRvY2RlbW86NjVhMDgzYjk1MYmNkNzUxYmJiY2U=' \
--header 'Cookie: _cfuvid=BNm80wogtZv7lPgRUsybHmAv_l_3VQCTg-1772103718132-0.0.1.1-604800000' \
--data '{
  "customerId": 566881933,
  "earnedFromType": "ACTIVITY",
  "earnedFromId": "TXN_12345_ABC",
  "eventTime": 1761748253000,
  "supplementaryCriteria": {
    "loyaltyProgramId": 874,
    "programType": "TIER",
    "partnerProgramId": 25319
  },
  "eventDetails": {
    "id": "TXN_12345_ABC",
    "type": "TransactionAdd",
    "eventPayload": {
      "storeId": 101,
      "amount": 75.50
    }
  }
}'

Prerequisites

Authentication: Basic or OAuth authentication.
Default access group

Resource information


Pagination	No
Batch support	No

Path parameters

Field	Type	Required	Description
promotionId	string	Yes	Defines the unique identifier of the cart promotion being earned.

Body parameters

Field	Type	Required	Description
customerId	Long	Yes	Specifies the unique identifier for the customer earning the cart promotion.
earnedFromType	Enum	Yes	Specifies how the cart promotion was earned. Supported values: • ACTIVITY: Earned through a customer action such as a transaction, registration, or profile update. • MILESTONE: Earned by achieving a predefined milestone from a tracker (e.g., 5th transaction, spending $1000 total). • REWARD: Granted as a reward through a loyalty redemption or external integration. • BULK_ISSUE: Granted via a bulk operation. For single-customer earns, use one of the other types.
earnedFromId	String	Yes	Specifies a unique identifier for this earning event. Use a reference that identifies the source of the earning, such as the transaction number (e.g., `TXN_12345_ABC`), milestone ID, or reward issuance ID.
eventTimeISO	Long	Conditional	Defines the timestamp when the earning event occurred in ISO 8601 format, including the region offset. The promotion uses this timestamp to determine whether the earning is valid. A past timestamp can be provided if the earning is being recorded after the event occurred, as long as it falls within the promotion's active earning period. For example: The earning event occurred at 14:30:53 on October 29, 2025, in India. Format for the request parameter: 2025-10-29T14:30:53+05:30.
eventTime	String	Conditional	Defines the timestamp when the customer performed the activity, in epoch milliseconds. This date can be set up to 24 hours in the future from the current time. A past date can be entered to record an earning against an older transaction. The promotion uses this timestamp to determine whether the earning is valid. A past timestamp can be provided if the earning is being recorded after the event occurred, as long as it falls within the promotion's active earning period. Note: This field will be deprecated in the future and is being replaced by eventTimeISO.
supplementaryCriteria	Object	Optional	Associate the earned promotion with a specific loyalty tier or subscription program. Use this when the customer should earn the promotion under a particular program context.
.loyaltyProgramId	Integer	Conditional	The ID of the loyalty program. Required when `supplementaryCriteria` is provided.
.programType	Enum	Conditional	The type of program. Required when `supplementaryCriteria` is provided. Supported values: • `TIER`: Associates the earn with a specific loyalty tier. • `SUBSCRIPTION`: Associates the earn with a specific subscription.
.partnerProgramId	Integer	Conditional	The ID of the specific tier or subscription within the program. Required when `supplementaryCriteria` is provided.
eventDetails	Object	Yes	Specifies the details about the triggering event.
.id	String	Yes	Specifies a unique identifier for the triggering event. Use the transaction number, registration ID, or another unique reference from the source system. This ID helps trace the earn back to its source event.
.type	String	Yes	Specifies the type of event that triggered the earning. Possible values: `TransactionAdd`, `CustomerRegistration`, `CustomerUpdate`.
.eventPayload	Object	Optional	Defines additional context about the triggering event in key-value format. Include relevant details from the event, such as `storeId`, `amount`, or `billNumber` for transactions. See eventPayload examples below.

`eventPayload` examples

The eventPayload object stores additional context about the triggering event. The structure depends on the event type.

For TransactionAdd events:

"eventPayload": {
  "storeId": 101,
  "amount": 75.50,
  "billNumber": "BILL-2025-001234"
}

For CustomerRegistration events:

"eventPayload": {
  "registrationSource": "MOBILE_APP",
  "storeId": 205
}

For CustomerUpdate events:

"eventPayload": {
  "updatedFields": ["email", "mobile"],
  "updateSource": "WEB_PORTAL"
}

For MILESTONE events:

"eventPayload": {
  "milestoneName": "5th_purchase",
  "milestoneId": 12345,
  "transactionId": "TXN_98765"
}

Example response

{
    "data": {
        "id": "6905ad0ecd58392443591e92",
        "customerId": 567205858,
        "promotionId": "6905a9ffb1cfc114606f7d0f",
        "earnedFromType": "ACTIVITY",
        "earnedFromId": "TXN_12345_ABC",
        "eventTime": 1761748253000,
        "eventTimeISO": "2025-10-29T14:30:53Z",
        "eventDetails": {
            "id": "TXN_12345_ABC",
            "type": "TransactionAdd",
            "eventPayload": {
                "storeId": 101,
                "amount": 75.5
            }
        },
        "validTill": 1825085406000,
        "validTillISO": "2027-11-01T16:10:06Z"
    }
}

Response parameters

Field	Type	Description
data	Object	Defines the container for the details of the successfully created earning cart promotion.
.id	String	Specifies the unique identifier for this earning cart promotion.
.customerId	Long	Specifies the ID of the customer who earned the cart promotion.
.promotionId	String	Specifies the ID of the cart promotion definition that was earned.
.earnedFromType	Enum	Indicates how the cart promotion was earned.
.earnedFromId	String	Indicates the identifier related to the earning trigger.
.eventTime	Long	Specifies the timestamp when the earning occurred in UTC timezone. Time format: Unix epoch milliseconds.
.eventTimeISO	String	Specifies the earning timestamp in UTC in ISO 8601 format, returned in the server time zone. EU server example 2026-02-04T09:16:30Z → 04 February 2026, 09:16:30 (UTC) India server example 2026-02-04T14:46:30+05:30 → 04 February 2026, 14:46:30 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
.eventDetails	Object	Defines details about the triggering event.
.validTill	Long	Specifies the timestamp when this earning cart promotion expires. Calculated based on cart promotion configuration.
.validTillISO	String	Specifies the expiry timestamp in UTC in ISO 8601 format, returned in the server time zone. EU server example 2026-02-04T09:18:12Z → 04 February 2026, 09:18:12 (UTC) India server example 2026-02-04T14:48:12+05:30 → 04 February 2026, 14:48:12 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
errors	Array	Defines an array of error objects.

Error codes

Code	Description
400	Bad Request: Indicates an invalid request body. Check required fields, data types , enum values, or JSON format.
401	Unauthorized: Indicates invalid or missing authentication credentials.
403	Forbidden: Indicates insufficient permissions to trigger cart promotion earnings.
404	Not Found: Indicates the specified cart promotionId in the URL does not exist.
409	Conflict: Indicates a potential business rule violation.
500	Internal Server Error: Indicates an unexpected server error occurred. Retry the request.