PromoIQ API · Self-Managed Commerce

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.