Earn Cart Promotions in Bulk

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

The bulk earn cart promotion API enables the immediate granting of multiple cart promotions to a specific customer in a single request.

Example request

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions/earn/bulk' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
--header 'Authorization: Basic Z2Vvcmd2RlbW81OTNhMjI2MTk1OGE2NWI5ZjAxMzU5NGIwNDllZTk=' \
--header 'Cookie: _cfuvid=GAReJgp167bbzDQ8s5vEdbLfhfncjBmtRbikkGl8-1762840589756-0.0.1.1-604800000' \
--data '{
  "orgId": 100737,
  "customerId": 566881933,
  "eventTime": 1761750000000,
  "earnedFromType": "BULK_ISSUE",
  "eventDetails": {
    "id": "6911e951f57b486147effa6c",
    "type": "BULK_ISSUE"
  },
  "earnedPromotions": [
    {
      "promotionId":"6912ced9d39e256f754a83f8",
      "earnCount": 1,
      "earnedFromId": "68fb1c9731d91c625a8d9e80"
    },
    {
      "promotionId":"6912cfff6629ee07040e15ef",
      "earnCount": 1,
      "earnedFromId": "68fb1c9731d91c625a8d9e80"
    }
  ]
  
}
'

Prerequisites

Authentication: Basic or OAuth authentication.
Default access group

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.

Body parameters

Field	Type	Required	Description
orgId	Integer	Optional	Specifies the organization ID.
customerId	Long	Yes	Specifies the unique identifier of the customer earning the cart promotions.
eventTime	Long	Yes	Specifies the timestamp when the bulk earning event occurred in UTC. Time format : epoch timestamp in milliseconds
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.
eventDetails	Object	Yes	Defines contextual details about the triggering event for this bulk operation. Example: "eventDetails": `{ "id": "6911e951f57b486147effa6c", "type": "BULK_ISSUE" }`
.id	String	Yes	Specifies the unique ID of the event or bulk operation reference.
.type	String	Yes	Specifies the type of event. Consistent with earnedFromType. 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.
earnedPromotions	Object	Yes	Defines a list of cart promotions to be earned by the customer in this request. Min items: 1.
.promotionId	String	Yes	Specifies the unique identifier of the specific cart promotion being earned.
.earnCount	Integer	Yes	Specifies the number of times this specific cart promotion should be earned. Must be 1 or greater.
.earnedFromId	String	Yes	Indicates a unique identifier for this specific earning within the bulk operation.

Example response

{
    "data": [
        {
            "earnedFromId": "68fb1c9731d91c625a8d9e80",
            "promotionId": "6912cfff6629ee07040e15ef",
            "successfulEarnCount": 1,
            "failedEarnCount": 0,
            "customerEarnedPromotions": [
                {
                    "id": "6912d0256629ee07040e15f2",
                    "customerId": 566881933,
                    "promotionId": "6912cfff6629ee07040e15ef",
                    "earnedFromType": "BULK_ISSUE",
                    "earnedFromId": "68fb1c9731d91c625a8d9e80",
                    "eventTime": 1761750000000,
                    "eventTimeISO": "2025-10-29T15:00:00Z",
                    "eventDetails": {
                        "id": "6911e951f57b486147effa6c",
                        "type": "BULK_ISSUE"
                    },
                    "validTill": 1767205799999,
                    "validTillISO": "2025-12-31T18:29:59Z"
                }
            ]
        },
        {
            "earnedFromId": "68fb1c9731d91c625a8d9e80",
            "promotionId": "6912ced9d39e256f754a83f8",
            "successfulEarnCount": 1,
            "failedEarnCount": 0,
            "customerEarnedPromotions": [
                {
                    "id": "6912d0256629ee07040e15f1",
                    "customerId": 566881933,
                    "promotionId": "6912ced9d39e256f754a83f8",
                    "earnedFromType": "BULK_ISSUE",
                    "earnedFromId": "68fb1c9731d91c625a8d9e80",
                    "eventTime": 1761750000000,
                    "eventTimeISO": "2025-10-29T15:00:00Z",
                    "eventDetails": {
                        "id": "6911e951f57b486147effa6c",
                        "type": "BULK_ISSUE"
                    },
                    "validTill": 1767205799999,
                    "validTillISO": "2025-12-31T18:29:59Z"
                }
            ]
        }
    ],
    "errors": []
}

Response parameters

Field	Type	Description
data	Array[Object]	Defines a list of results , one for each entry in the request's earnedPromotions array.
.earnedFromId	String	Indicates the unique identifier provided in the request for this specific earning instance.
.promotionId	String	Specifies the cart promotion ID from the corresponding request entry.
.successfulEarnCount	Integer	Indicates how many instances specified by earnCount were successfully created.
.failedEarnCount	Integer	Indicates how many instances specified by earnCount failed to be created.
.errorDetails	Object	Defines details about the failure, present only if failedEarnCount > 0.
...errorCode	Integer	Specifies a code indicating the reason for failure.
...errorMessages	String	Specifies a descriptive message explaining the failure.
.customerEarnedPromotions	Array[Object]	Defines a list containing the details of each successfully created earning cart promotion for this entry.
....id	String	Specifies the unique identifier (earnId) for the successfully created earning cart promotion.
....customerId	Long	Specifies the ID of the customer.
....promotionId	String	Specifies the ID of the cart promotion definition.
....earnedFromType	Enum	Indicates how the cart promotion was earned.
....earnedFromId	String	Indicates the identifier for this specific earning instance.
....eventTime	Long	Specifies the timestamp when the earning occurred.
....eventTimeISO	String	Specifies the earning timestamp in UTC. Time format : ISO 8601
....eventDetails	Object	Defines details about the triggering event.
....validTill	Long	Specifies the expiry timestamp in UTC for this earned cart promotion. Time format : Unix epoch milliseconds
....validTillISO	String	Specifies the expiry timestamp in UTC. Time format : ISO 8601
errors	Array	Defines an array for errors encountered.

Language

Credentials

Basic

base64

URL

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