Promotion List — XML Reference

List promotions using the supplied filters and pagination controls. Use Promotion Get (40110) to retrieve an individual promotion definition.

Endpoint and formats

POST /api/{companyKey}/promotions/list

Send Content-Type: application/xml. Select the service host and company key documented in the API Reference. Normal application responses use HTTP 200; inspect summary.result and summary.messages for success or failure.

WCF service and method

Method PromotionList

Environment	WCF service address
Evaluation/Development	`https://evaluation.qixolpromo.com/ConfigurationService.svc`
Production	`https://datamanager.qixolpromo.com/ConfigurationService.svc`

Service contract string PromotionList(string listRequestXml)

Use the WCF service contract to determine method parameters and message wrapping. The XML examples below describe the business payload. See WCF integration guidance.

XML Request Example

These examples illustrate the XML request and response structure. Use your own company data and the operation’s schema when building requests; promotion results depend on your company configuration.

<request>
 <pagination>
 <page>1</page>
 <pagesize>20</pagesize>
 </pagination>
 </request>

XML Response Example

Example XML response. Actual values depend on the request and configured promotions.

<response>
 <summary result="true" filtered="false">
 <action id="40100">Promotion List</action>
 <messages/>
 <status>Retrieved</status>
 </summary>
 <pagination>
 <page>1</page>
 <pagesize>20</pagesize>
 <totalitemcount>2</totalitemcount>
 <totalpagecount>1</totalpagecount>
 </pagination>
 <promotions>
 <promotion id="1" type="BASKETREDUCTION" validfrom="2026-01-01T00:00:00" validto="2028-12-31T23:59:59" published="true" locked="false" alwaysapply="false" activenow="true" inuse="false">
 <name>10% off with coupon</name>
 <displaytype>Basket % or value off</displaytype>
 <promotiongroupname>SAMPLE</promotiongroupname>
 </promotion>
 <promotion id="2" type="BOGOF" validfrom="2026-01-01T00:00:00" validto="2028-12-31T23:59:59" published="true" locked="false" alwaysapply="false" activenow="true" inuse="false">
 <name>Buy one get one free on all Shoes</name>
 <displaytype>Buy one get one free</displaytype>
 <promotiongroupname>SAMPLE</promotiongroupname>
 </promotion>
 </promotions>
</response>

Illustrative XML Failure Response

Illustrative failure response (not captured from a live API call). The actual error code and message depend on the failure.

<response><summary result="false"><messages><message code="IM190">A problem was encountered deserializing the request data.</message></messages></summary></response>

XML Schemas (XSD)

These XML Schema Definition (XSD) files define the supported XML request and response structures, including elements, attributes, data types and validation constraints. Use them to validate XML payloads when integrating with the QixolPromo API.

XML Validation Notes

The unfiltered example retains the earlier correction omitting optional criteria. The historical filtered sample omitted a criteria/id element required by its XML XSD. JSON criteria and XML criteria must be checked against their own schemas.

Preserve the XML root, attributes, nested elements and collection wrappers shown above; JSON-shaped objects are not XML request documents.
Follow the XSD’s element/attribute distinctions, compositor rules, cardinalities, enumerations and value limits. Examples are complete samples, not exhaustive demonstrations of every optional branch.
Repeating elements are validated against the XSD; do not flatten a collection into attributes or change item names.
Validate XML before sending it. For example, download the linked request XSD, save the XML request example as request.xml in the same folder, and run:

xmllint --noout --schema QPSchema_Configuration_PromotionList_Request.xsd request.xml

Save the XML response as response.xml alongside the downloaded response XSD, then run:

xmllint --noout --schema QPSchema_Configuration_PromotionList_Response.xsd response.xml

The optional criteria block is omitted, preserving the v1.0.1/v1.0.2 correction. The older filtered sample omits a criteria/id element required by its XSD; an empty id element is permitted by that schema.

Sending XML Requests

To submit an XML request, use the XML Request Example provided above.

Set the HTTP Content-Type header to application/xml and send the XML payload to the appropriate QixolPromo API endpoint.

You can use any HTTP client that supports XML request bodies, such as Postman or cURL.

The corresponding XSD files are available above to help validate your XML requests and responses. For the browser walkthrough and response viewer, see Test an XML request.

Return to API Reference — Promotion List.

API access and security

Services Interaction Keys (API keys) for evaluation companies can be obtained through the QixolPromo Portal; production keys are supplied directly by Qixol. Production API access is IP-restricted by default, unless Qixol disables the restriction. Permitted IP addresses are configured in the Portal under Configuration → Permitted IP Addresses; allowlist changes may take up to 24 hours. Evaluation companies have no IP restrictions. Basket operations use Basket Service Access; other operations use Data Management Service Access. Keep keys confidential.