This API grants multiple cart promotions to a customer in a single request.

When you call this API, the system immediately adds all specified promotions to the customer's wallet, making them available for redemption.
Use this API when you need to award several promotions to a customer at once, such as during a batch processing operation or as part of a loyalty program milestone.
You can specify different earn counts for each promotion in the earnedPromotions array to control how many times each promotion is granted.
To earn a single promotion for a customer, use the Earn Cart Promotion API instead.

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

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	Conditional	Specifies the timestamp when the bulk earning event occurred in UTC. The promotion uses this timestamp to determine whether the earnings are 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. Time format : epoch timestamp in milliseconds Note: This field will be deprecated in the future and is being replaced by `eventTimeISO`.
eventTimeISO	String	Conditional	Defines the timestamp when the bulk earning event occurred in ISO 8601 format, including the region offset. The promotion uses this timestamp to determine whether the earnings are 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 bulk earning event occurred at 14:30:45 on December 16, 2025, in India. Format for the request parameter: 2025-12-16T14:30:45+05:30.
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 in ISO 8601 format, returned in the server time zone. EU server example 2026-02-04T09:08:48Z → 04 February 2026, 09:08:48 (UTC) India server example 2026-02-04T14:38:48+05:30 → 04 February 2026, 14:38:48 (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 expiry timestamp in UTC for this earned cart promotion. Time format : Unix epoch milliseconds
....validTillISO	String	Specifies the expiry timestamp in UTC in ISO 8601 format, returned in the server time zone. EU server example 2026-02-04T09:09:30Z → 04 February 2026, 09:09:30 (UTC) India server example 2026-02-04T14:39:30+05:30 → 04 February 2026, 14:39:30 (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 for errors encountered.

Error codes

Code	Description
400	Invalid request. Check required parameters. Ensure all required parameters (such as promotion and customer details) are valid.
404	Promotion or customer not found. Use valid, existing promotion and customer identifiers.
705	Exceeded maximum active promotions for an org. Deactivate some active promotions before issuing more in bulk.
706	Promotion has expired. Use a valid, non-expired promotion.
707	The passed promotion type is not supported. Change the promotion type to one supported by the system.
713	Earned from type cannot be changed. Do not change `earnedFromType` on existing earned promotions.
714	Earn is not supported for this promotion type. Switch to a promotion type that supports earning.
1006	Invalid customer identifier. Provide a valid customer identifier for every request in the bulk call.
1007	Error while fetching customer identifier. Retry and validate all customer data in your bulk payload.
500	Internal server error. Retry the request after a short delay, and contact support if the error persists.

200200

400400