This API issues a cart promotion to one or more customers.

When you call this API, the system adds the specified promotion to each customer's wallet, making it available for redemption at checkout.
Use this API when you want to manually award a promotion to specific customers, such as for targeted campaigns, or compensation.
You can issue the same promotion to multiple customers in a single request by passing an array of customer IDs in the request body.
The contextId parameter identifies the specific issuance context, which is useful for tracking and managing promotion grants.

👍
Note
For detailed information about the APIs and for hands-on testing, refer to the API overview documentation and step-by-step guide on making your first API call.

Example request

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions/69117663b1cfc114606fd7fb/issueBulk?contextId=68fb1c9731d91c625a8d9e80' \
--header 'Content-Type: application/json' \6NzYzNDkxOGFmNDI3MGQ3YzI4ZjU4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=IBM60ka7X5Aybk9Gp8JKVHig14rVuwA5XcyAUA-1747041228297-0.0.1.1-604800000; _cfuvid=fVY1aFlJcxMfPAsl7lBGJQG55iNNKmYw08.WciBy9eY-1747126931365-0.0.1.1-604800000; _cfuvid=.SKkqn5X9vb1GQsCWsMQPXos7ah5dTOcOGwZsXgVL14-1762781673638-0.0.1.1-604800000' \
--data '[
  566881933
]'

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions/69117663b1cfc114606fd7fb/issueBulk?contextId=68fb1c9731d91c625a8d9e80' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmJ1a2OGFmNDI3MGQ3YzI4ZjU4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=IBM60ka7X5Ayb_p8JKVHig14rVuwA5XcyAUA-1747041228297-0.0.1.1-604800000; _cfuvid=fVY1aFlJcxMfPAsl7lBGJQG55iNNKmYw08.WciBy9eY-1747126931365-0.0.1.1-604800000; _cfuvid=45d7g9Neek04LsBJTGQFH8PZDfBL6q07KlMwvdtpVcQ-1762781521742-0.0.1.1-604800000' \
--data '[
  566881933, 566135941
]'

Prerequisites

Authentication - Basic or OAuth authentication
Access group resource - Write access to customer group resource
Cart promotionId and customerId

Resource Information

URI	promotions/{promotionId}/issueBulk
Rate Limit	NA
Batch support	Yes

Path Parameter

Parameter (Parameters marked as * are required)	Data Type	Description
promotionId*	String	ID of cart promotion that is generated when creating a cart promotion. Use the get promotions for a customer API to get the promotionId for the Cart Promotion.

Query Parameter

Parameter (Parameters marked as * are required)	Data Type	Description
contextId*	String	Unique identifier of the issued promotion. It is used to identify the particular promotion.

Request Body

[
  564332013
]

Request Body Parameters

Parameter Name	Data Type	Description
customerId	Long	Unique identifier of the customer.

Response Body

{
    "data": {
        "564332013": {
            "id": "68230a3af1ebc84977d9ea2c",
            "customerId": 564332013,
            "promotionId": "67f3832ab206f929966adf81",
            "earnedFromId": "2 items in cart",
            "eventTime": 1747126842954,
            "validTill": 1748716199999
        }
    }
}

Response Body Parameters

Parameter	Data Type	Description
data	Object	Object containing details of the customer and issued cart promotion.
-- id	String	The unique identifier for the issued promotion.
-- customerId	Long	The ID of the customer to whom the promotion was issued.
-- promotionId	String	The ID of the promotion that was issued.
-- earnedFromId	String	The context ID that was passed in the API request, used to track the source of the issuance.
-- eventTime	Long	The timestamp (in milliseconds) when the promotion was issued.
-- validTill	Long	The timestamp (in milliseconds) until which the issued promotion is valid.

Error codes

Code	Description
400	Invalid request. Check required parameters. Ensure all required parameters (including a valid `promotionId` and customer data) are valid.
404	Promotion or customer not found. Use valid and existing `promotionId` 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 for the issuance.
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. The customer IDs array is empty, contains null values, or includes invalid identifiers. Provide a valid, non-empty array of customer identifiers.
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

404404