PromoIQ API
The PromoIQ API exposes endpoints for evaluating promotions against products and shopping carts, retrieving promotion rules and coupons, and managing how coupons are assigned and validated for customers. It is intended to let external systems integrate Self-Managed Commerce promotion logic into their own commerce experiences.
All endpoints are rooted at the Integration Server context path. For example, the full base for the endpoints below is:
GET integration/api/promoiq/v1/promotions/...
All Integration Server endpoints, including these APIs, require authentication. For more information, see Integration Server API Security.
An OpenAPI specification covering the full request and response schemas is available at:
GET integration/api/promoiq/v1/promotions/api-docs
The PromoIQ API uses a number of Extension Point Framework types for its request and response bodies, such as XPFCartPromotionsCalculatorInputContext and XPFPromotionRule. The descriptions below summarize the role of each input and output type; refer to the OpenAPI specification above for the full field-by-field schema.
Error Responses
When a request fails, the response body is a JSON string containing the failure detail.
| Status Code | Condition |
|---|---|
400 Bad Request | Returned when the request body is invalid JSON, a required field is missing, or a required query parameter is missing or empty. The response body contains the validation message. |
500 Internal Server Error | Returned when the request fails for any other reason. The response body contains the exception class and message. |
Promotion Endpoints
These endpoints are implemented in PromotionRestEndpointRouteBuilder. They evaluate promotion logic for a single product SKU or a shopping cart and retrieve metadata for individual promotion rules.
Fetch Promotion Rules
GET integration/api/promoiq/v1/promotions
Returns promotion rule details for the supplied list of GUIDs.
| Query Parameter | Required | Description | Example |
|---|---|---|---|
guids | Yes | Comma-separated list of promotion rule GUIDs. | rule-guid-1,rule-guid-2 |
Success (200 OK): A JSON object mapping each requested GUID to its corresponding XPFPromotionRule representation. GUIDs that do not resolve to a known rule are omitted from the response.
Evaluate Product Actions
POST integration/api/promoiq/v1/promotions/evaluate-product-actions
Evaluates catalog (product) promotions for a single product SKU and returns the promotion actions that apply.
Request body: An XPFCatalogPromotionsCalculatorInputContext containing the product SKU, store, currency, and customer tags used to drive the evaluation.
Success (200 OK): An XPFPromotionsCalculatorOutputContext containing the list of applicable promotion actions (XPFPromotionAction) for the supplied SKU.
Evaluate Cart Actions
POST integration/api/promoiq/v1/promotions/evaluate-cart-actions
Evaluates shopping-cart promotions for a cart and returns the promotion actions that apply.
Request body: An XPFCartPromotionsCalculatorInputContext containing the shopping cart, store, currency, evaluation stage, and customer tags.
Success (200 OK): An XPFPromotionsCalculatorOutputContext containing the list of applicable promotion actions for the supplied cart.
Evaluate Product Carrots
POST integration/api/promoiq/v1/promotions/evaluate-product-carrots
Returns the set of "carrots" — promotion actions that would become applicable to the supplied product SKU if the shopper takes specific actions, such as adding more of the item to the cart.
Request body: An XPFPromotionCarrotsInputContext containing the product SKU, shopper, currency, and customer tags.
Success (200 OK): A JSON array of XPFPromotionAction objects representing the available carrots.
Coupon Endpoints
These endpoints are implemented in CouponRestEndpointRouteBuilder. They provide read access to coupons and coupon groups, validate coupon usage, and let external systems manage which coupons are assigned to a customer or auto-applied to a customer's cart.
Fetch Coupons by GUID
GET integration/api/promoiq/v1/promotions/coupons
Returns coupon details for the supplied list of coupon GUIDs.
| Query Parameter | Required | Description | Example |
|---|---|---|---|
guids | Yes | Comma-separated list of coupon GUIDs. | coupon-guid-1,coupon-guid-2 |
Success (200 OK): A JSON object mapping each requested GUID to its XPFCoupon representation.
Trigger Actions at Checkout
POST integration/api/promoiq/v1/promotions/coupons/trigger-actions-at-checkout
This API should be invoked when an order is checked out with a set of applied promotions. It inspects the supplied list of promotion rules and, for any rule that has an "Assign coupon" action, creates the corresponding coupons for the specified customer email so that they apply to that customer's cart.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
customerEmail | string | Yes | Email address of the customer to assign coupons to. |
appliedRuleGuids | array of strings | Yes | Promotion rule GUIDs to inspect for coupon-assignment actions. |
Example:
{
"customerEmail": "cust@example.com",
"appliedRuleGuids": ["rule1", "rule2"]
}
Success (204 No Content): No response body. The coupons have been assigned to the customer's cart.
Validate Coupon Usage
POST integration/api/promoiq/v1/promotions/coupons/validate-usage
Validates whether the supplied coupon codes are usable by the given customer in the given store, taking promotion rule conditions and per-customer usage limits into account.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
couponCodes | array of strings | Yes | Coupon codes to validate. |
storeCode | string | Yes | Code of the store for which to validate the coupons. |
customerEmail | string | Yes | Email address of the customer for which to validate the coupons. |
Example:
{
"couponCodes": ["code1", "code2"],
"storeCode": "store1",
"customerEmail": "cust@example.com"
}
Success (200 OK): A JSON object mapping each supplied coupon code to its XPFPromotionCouponValidationOutputContext, which indicates whether the code is valid and, if not, why.
Disable Cart Auto-Apply
POST integration/api/promoiq/v1/promotions/coupons/disable-cart-auto-apply
Disables the automatic application of the supplied coupon codes to the given customer's cart. After this call, the coupons remain available to the customer but are not applied automatically.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
customerEmail | string | Yes | Email address of the customer. |
couponCodes | array of strings | Yes | Coupon codes to stop auto-applying. |
Example:
{
"customerEmail": "cust@example.com",
"couponCodes": ["code1", "code2"]
}
Success (204 No Content): No response body. Automatic application has been disabled for the supplied coupon codes.
Fetch Coupon Groups by Code
GET integration/api/promoiq/v1/promotions/coupon-groups
Returns the collection of coupons in the coupon groups that contain the supplied coupon codes. Use this endpoint when one shopper-facing code represents a set of underlying coupons.
| Query Parameter | Required | Description | Example |
|---|---|---|---|
codes | Yes | Comma-separated list of coupon codes. | WELCOME10,SUMMER25 |
Success (200 OK): A JSON object mapping each supplied coupon code to the collection of XPFCoupon objects that belong to its coupon group.
Search Coupon Codes by Customer
POST integration/api/promoiq/v1/promotions/coupon-codes/search-by-customer
Returns the coupon codes that are assigned to the given customer and applicable in the given store.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
customerEmail | string | Yes | Email address of the customer. |
storeCode | string | Yes | Code of the store. |
Example:
{
"customerEmail": "cust@example.com",
"storeCode": "store1"
}
Success (200 OK): A JSON array of coupon codes available to the customer in that store.