Earn Cart Promotion

post https://{host}/api_gateway/v1/promotions/{promotionId}/earn

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://{Host}/api_gateway/v1/promotions/6905a9ffb1cfc114606f7d0f/earn' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmJ1a2w6NzNDkxOZjU4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=jNvilmDWuR7ZrrAPT99zZDUXtjJoxe_VUUWJf6
--data '{
  "customerId": 567205858,
  "earnedFromType": "ACTIVITY",
  "earnedFromId": "TXN_12345_ABC",
  "eventTime": 1761748253000,
  "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

Rate limit

Demo and Testing Clusters: 1,000 requests per minute per API key
Other Organizations: The rate limit is brand-specific.

To modify the limit, create a ticket with the Capillary Product support team.

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: • BULK_ISSUE: Cart promotion granted via a bulk operation. ACTIVITY: Triggered by a specific customer event. • MILESTONE: Triggered by achieving a predefined milestone. • REWARD: Granted as a reward.
earnedFromId	String	Yes	Defines the unique ID generated after issuing the cart promotion.
eventTime	Long	Yes	Specifies the timestamp when the earning event occurred, in UTC. Time format: epoch timestamp in milliseconds. Example: 1761748253000.
eventDetails	Object	Yes	Specifies the details about the triggering event.
.id	String	Yes	Specifies the unique ID of the event itself. Often matches `earnedFromId`.
.type	String	Yes	Specifies the type of event that triggered the earning. Possible values: `TransactionAdd`, `CustomerRegistration`, `CustomerUpdate`.
.eventPayload	Object	Optional	Defines a key-value map for storing additional event data. The structure is user-defined Eg., {"storeId": 101, "amount": 75.50}).

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 timezone. Time format: ISO 8601 format.
.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 timezone. Time format: ISO 8601 format.
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.

Language

Credentials

Basic

base64

URL

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