Retrieve cart promotion details for your organization.

When you call this API, the system returns a list of all cart promotions configured for your organization, including their conditions, actions, restrictions, and status.
Use this API to build a promotions management dashboard, audit your active promotions, or integrate promotion data with external systems.
You can filter results by promotion IDs, status (active/inactive), type, and sort by fields such as LAST_UPDATED_ON or ID.
This API supports pagination using limit and offset parameters for handling large numbers of promotions.

Example request

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions/?sortOn=LAST_UPDATED_ON&order=DESC' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmRvY2RlbW86NjVhMDg5MGY1NTY5NDk1YmNkNzUxYmJiY2U=' \
--header 'Cookie: _cfuvid=9oSiCR7BHQMrLE46iRVUQNbpmzDGiM-1756730125036-0.0.1.1-604800000; _cfuvid=y3NwvAkrzj8eN_r9Ks6WPVYJSZAsNHmZQJQ-1756803208058-0.0.1.1-604800000; _cfuvid=EJWlRAIOoMHMsycvp_BC3tmpSyOoT_kKMy.AQIK5OxE-1772099122620-0.0.1.1-604800000; _cfuvid=iq3rySWzm7tr4w_yKvyaHwdA0NYITYLAm9AdUG0sLmc-1772434703644-0.0.1.1-604800000'

Prerequisites

Authentication: Basic or OAuth authentication
Access group resource: Default

Resource information


Pagination support	Yes
Batch support	Yes

Query parameters

Field	Type	Required	Description
promotionIds	Array	Optional	Unique identifiers for the cart promotion, generated during the creation of the cart promotion. Accepts multiple comma-separated IDs. Maximum 20 IDs per request.
active	Boolean	Optional	If `true`, returns only active promotions. If `false`, returns only inactive promotions.
name	String	Optional	Searches for promotions matching the specified name.
startDate	Long	Optional	Filters promotions by start date. Use with `startDateOperator`. Time format: Epoch milliseconds.
startDateOperator	Enum	Optional	Operator for filtering by start date. Supported values: `LESS_THAN`, `GREATER_THAN`. Required when using `startDate`.
endDate	Long	Optional	Filters promotions by end date. Use with `endDateOperator`. Time format: Epoch milliseconds.
endDateOperator	Enum	Optional	Operator for filtering by end date. Supported values: `LESS_THAN`, `GREATER_THAN`. Required when using `endDate`.
campaignId	Long	Optional	Filters promotions by the associated campaign identifier.
sortOn	Enum	Optional	Field to sort the results by. Supported values: `ID` (default): Sorts based on the cart promotion id `NAME`: Sorts based on the promotion name. `START_DATE`: Filters based on the starting date of the cart promotion. `LAST_UPDATED_ON`: Sorts based on when the promotion was last modified.
order	Enum	Optional	Sort order direction. Supported values: `ASC` (ascending, default), `DESC` (descending).
pageNumber	Integer	Optional	Page number for paginated results. Starts from 0.
limit	Integer	Optional	Number of results to return per page.

Example response

{
  "data": [
    {
      "id": "68b5401db51b7777eca02900",
      "name": "SeptemberPromo",
      "orgId": 100737,
      "priority": 0,
      "active": true,
      "messageLabel": "",
      "type": "CUSTOMER",
      "condition": {
        "type": "CART",
        "cartCondition": {
          "kpi": "SUBTOTAL",
          "operator": "GREATER_THAN_OR_EQUAL",
          "value": "500.000000"
        }
      },
      "action": {
        "type": "CART_BASED",
        "cartBasedAction": {
          "type": "PERCENTAGE",
          "value": "15.000000"
        }
      },
      "createdBy": 75139931,
      "createdOn": 1756708893457,
      "createdOnISO": "2025-09-01T06:41:33Z",
      "lastUpdatedBy": 75139931,
      "lastUpdatedOn": 1756709902063,
      "lastUpdatedOnISO": "2025-09-01T06:58:22Z",
      "startDate": 1756665000000,
      "startDateISO": "2025-08-31T18:30:00Z",
      "endDate": 1759256999999,
      "endDateISO": "2025-09-30T18:29:59Z",
      "campaignId": 264140,
      "promotionRestrictions": {},
      "earnLimitedToSpecificAudience": true,
      "customFieldValues": {},
      "customerActivationRequired": false,
      "mode": "DISCOUNT",
      "maxIssuancePerCustomer": -1,
      "isStackable": false
    }
  ]
}

Response parameters

Field	Type	Description
data	Array	List of cart promotion objects.
.id	String	Unique identifier of the cart promotion.
.name	String	Name of the cart promotion.
.orgId	Integer	Organization identifier where the cart promotion exists.
.priority	Integer	Priority of the cart promotion. Lower value means higher priority.
.active	Boolean	Shows if the cart promotion is active. `true` - enabled, `false` - disabled.
.messageLabel	String	Custom label or message for the promotion.
.type	String	Type of cart promotion. Possible values: `CUSTOMER`, `POS`, `CODE`, `EARNING`, `REWARD`.
.condition	Object	Object containing information on the conditions.
..type	String	Type of condition applied. Possible values: `CART`, `PRODUCT`, `COMBO_PRODUCT`, `TENDER`.
..cartCondition	Object	Object containing the details of the conditions.
...kpi	String	KPI on which the condition is based. Possible values: `SUBTOTAL`, `ITEMCOUNT`.
...operator	String	Operator used for evaluation. Possible values: `EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN`, `LESS_THAN_OR_EQUAL`, `IN`, `NONE`.
...value	Integer	Value used in the condition check.
.action	Object	Object containing details of the action.
..type	String	Type of action triggered. Possible values: `CART_BASED`, `FIXED_PRICE`, `PRODUCT_BASED`, `FREE_PRODUCT`, `TENDER`, `PER_UNIT`.
..cartBasedAction	Object	Object containing cart-based action details.
...type	String	Type of benefit or discount applied. Possible values: `PERCENTAGE`, `ABSOLUTE`.
...value	Integer	Value of the discount.
.createdBy	Integer	User ID of the creator.
.createdOn	Integer	Timestamp when the cart promotion was created in epoch milliseconds.
.createdOnISO	String	Creation timestamp in ISO 8601 format.
.lastUpdatedBy	Integer	User ID of the last updater.
.lastUpdatedOn	Integer	Timestamp when the cart promotion was last updated in epoch milliseconds.
.lastUpdatedOnISO	String	Last updated timestamp in ISO 8601 format.
.startDate	Integer	Start date of the cart promotion in epoch milliseconds.
.startDateISO	String	Start date in ISO 8601 format.
.endDate	Integer	End date of the cart promotion in epoch milliseconds.
.endDateISO	String	End date in ISO 8601 format.
.campaignId	Integer	Campaign identifier.
.promotionRestrictions	Object	Restrictions for applying the promotion.
..Customer	Array	Customer-level redemption limits.
..Cart	Array	Cart-level redemption limits.
...kpi	String	Key metric used for the restriction.
...limit	String	Maximum allowed value for the restriction.
...windowType	Enum	Type of limit window applied to the restriction.
...fixedWindowConfig	Object	Cycle configuration when `windowType` is `FIXED`.
....cycleType	Enum	Type of fixed cycle.
....weekStartDay	Enum	Start day of the weekly cycle when `cycleType` is `WEEK`.
....refreshRate	Integer	Number of days per cycle when `cycleType` is `N_DAY`.
....cycleReferenceDate	Long	Epoch timestamp in milliseconds. Anchor date from which N_DAY cycles are calculated. Interpreted in the org's configured timezone. Defaults to the promotion's `startDate` if omitted.
.earnLimitedToSpecificAudience	Boolean	Indicates whether the cart promotion is limited to a specific audience.
.customFieldValues	Object	Custom fields or additional values.
.customerActivationRequired	Boolean	Whether customers must activate the cart promotion before use.
.mode	String	Mode of the promotion. Possible values: `DISCOUNT`, `PAYMENT_VOUCHER`.
.maxIssuancePerCustomer	Integer	Maximum times the promotion can be issued per customer. Maximum value: 50.
.isStackable	Boolean	Whether the promotion can be stacked with others.

Error and warning codes

Code	Type	Description
400	Error	Invalid request. Check required parameters.
500	Error	Internal server error. Retry the request after a short delay.
701	Error	Error while calling the segmentation engine.
702	Error	Error while getting org entities.
703	Error	Org timezone fetch failed.
704	Error	Invalid reward type passed.
705	Error	Exceeded maximum active promotions for an org.
706	Error	Promotion has expired.
707	Error	The passed promotion type is not supported.
708	Error	Exceeded the max earn per customer limit.
709	Error	Promotion not in running state.
710	Error	Error while saving earned promotion.
711	Error	Error while saving promotion or could not get product details.
712	Error	Error while creating/updating emf rules.
713	Error	Earned from type cannot be changed.
714	Error	Earn is not supported for this promotion type.
715	Error	Promotion was not issued to current customer.
716	Error	Promotion name must be unique.

200Successful operation (default from cURL)