post
https://{host}/api_gateway/v1/promotions//issueBulk
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
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
contextIdparameter identifies the specific issuance context, which is useful for tracking and managing promotion grants.
NoteFor 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. |