QixolPromo
Developer Guides / XML Reference / 10300
Basket · Operation 10300 · XML request and response reference

Validate Basket — XML Reference

Evaluate promotions for a basket and return the resulting prices, discounts and promotion details. Always reuse the same unique basket ID for the same transaction, including when the basket changes or is resubmitted after confirmation. Submit confirmed=false while the sale is provisional and confirmed=true when the sale is committed; confirmation may record persistent usage and issuance effects. Resubmitting a confirmed basket with the same ID does not repeat already-recorded coupon utilisation or voucher issuance, even if basket contents change. If a later adjustment invalidates an earlier promotion, the integrating platform must handle the adjustment: QixolPromo does not automatically reverse the prior utilisation or issuance. Delivery charges supplied on the basket header may appear as a delivery line in the response.

Endpoint and formats

POST /api/{companyKey}/basket/validate

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 ValidateBasket

EnvironmentWCF service address
Evaluation/Developmenthttps://evaluation.qixolpromo.com/BasketService.svc
Productionhttps://basketmanager.qixolpromo.com/BasketService.svc

Service contract string ValidateBasket(string basketXml)

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.

XML
<basket id="SAMPLE_BASKET_REF_001" basketdate="2026-06-20T14:00:00" store="WEB_STORE" channel="WEB" deliverymethod="NEXTDAY" baskettotal="45.97" manualdiscount="0" deliveryprice="5.99" deliverymanualdiscount="0" get_missed_promotions="false" confirmed="false">
 <coupons>
 <coupon code="SAMPLE_CODE1"/>
 </coupons>
 <items>
 <item id="1" productcode="PR-25" quantity="2" price="19.99" manualdiscount="0" isdelivery="false" alwaysexcluded="false" isgiftcard="false"/>
 </items>
</basket>

XML Response Example

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

XML
<response id="SAMPLE_BASKET_REF_001" date="2026-06-20T14:00:00" confirmed="false" channel="WEB" store="WEB_STORE" deliverymethod="NEXTDAY" manualdiscount="0" basketdiscount="2.00" linestotaldiscount="19.99" linestotalpromotiondiscount="19.99" linestotalmanualdiscount="0" totaldiscount="21.99" baskettotal="23.98" originalbaskettotal="45.97" deliverymanualdiscount="0" deliveryprice="5.99" deliverypromotiondiscount="0" deliverytotaldiscount="0" deliveryoriginalprice="5.99">
 <items>
 <item id="1" engineid="0" productcode="PR-25" price="19.99" manualdiscount="0" quantity="1" linepromotiondiscount="0" totaldiscount="0" originalprice="19.99" originalquantity="2" originalamount="39.98" appliedpromotioncount="2" isdelivery="false" lineamount="19.99">
 <description>adidas Consortium Campus 80s Running Shoes</description>
 <promotions>
 <promotion id="2" discountamount="2.00" instance="1" basketlevel="true" forlineid="1"/>
 <promotion id="1" discountamount="0" instance="1" forlineid="1"/>
 </promotions>
 </item>
 <item id="2" engineid="0" productcode="PR-25" price="0.00" manualdiscount="0" quantity="1" linepromotiondiscount="19.99" totaldiscount="19.99" originalprice="19.99" originalquantity="0" originalamount="0" appliedpromotioncount="1" splitfromlineid="1" isdelivery="false" generated="true" lineamount="0.00">
 <description>adidas Consortium Campus 80s Running Shoes</description>
 <promotions>
 <promotion id="1" discountamount="19.99" instance="1" forlineid="2"/>
 </promotions>
 </item>
 </items>
 <coupons>
 <coupon code="SAMPLE_CODE1" utilized="true" utilizeconfirmed="false" locksinuse="false">
 <utilizations>
 <promotion id="2" instance="1"/>
 </utilizations>
 <couponname>SAMPLE_SOURCE_CODE</couponname>
 <message code="CV100">The code has not been confirmed as utilized.</message>
 </coupon>
 </coupons>
 <summary result="true" promotionsapplied="2" vuid="08631c11-9fde">
 <action id="10300">Validate Basket</action>
 <messages/>
 <promotions>
 <promotion id="1" type="BOGOF" display="Buy one get one free" discountamount="19.99" instance="1">
 <name>Buy one get one free on all Shoes</name>
 <displaytext>Buy one pair, get another pair free</displaytext>
 </promotion>
 <promotion id="2" type="BASKETREDUCTION" display="Basket discount" discountamount="2.00" instance="1" basketlevel="true">
 <name>10% off with coupon</name>
 <displaytext>Get 10% off your basket</displaytext>
 </promotion>
 </promotions>
 </summary>
 <missedpromotions/>
</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.

XML
<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.

Basket Request Collections

  • JSON coupons[] contains codes submitted with the basket; it is not a list of campaigns returned by the API. XML uses the coupons wrapper and repeated coupon elements.
  • JSON items[] contains basket lines. XML uses items with repeated item elements; preserve line identifiers and XML attributes.
  • JSON attributes[] and line-level items[].attributes[] are token/value pairs for their respective scope. Do not assume these JSON arrays translate directly into identically named XML elements; follow the original XML XSD.
  • selectlists carries promotion select-list choices, not coupon codes. The JSON and XML schemas describe different wire shapes; in particular, the baseline XML XSD exposes a selection element while JSON has a selections collection. Confirm complex selection behaviour against the implementation before expanding that example.

XML Validation Notes

  • 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_Basket_Request_ValidateBasket.xsd request.xml

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

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

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 — Validate Basket.

Basket ID and repeated submissions

Always retain the same unique basket ID for a transaction, whether confirmed or unconfirmed, and when resubmitting changed contents. This prevents previously recorded coupon utilisation or voucher issuance from being performed again for that basket ID; it does not guarantee that every operation is fully idempotent. A changed, previously confirmed transaction may require adjustments in the integrating platform because earlier persistent effects are not automatically reversed.

Evaluation request limits

In Evaluation/Development, Validate Basket (10300) and Validate Coupon Code (10200) share a default limit of 10 requests per second. The limit can be configured for your company.

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.

Transaction safety and evaluation limit

In Evaluation/Development, Validate Basket (10300) and Validate Coupon Code (10200) share a default limit of 10 requests per second. The limit can be configured for your company. Production Basket requests are not subject to these evaluation limits. Keep the same basket ID throughout modification, confirmation and resubmission. Previously recorded coupon or voucher effects are not automatically reversed if a modified basket no longer qualifies.