Getting Started

This guide takes you from setting up API access to making your first Basket Evaluation request. You’ll learn how to choose an environment, supply your company key and interpret the result before adding QixolPromo to your checkout workflow.

Before you begin

To integrate with QixolPromo, you will need:

• A QixolPromo company containing suitable products and promotions.
• The company's Services Interaction Key.
• The API service URL for the environment you are accessing.
• An application or API client capable of making HTTPS requests with JSON.

The Services Interaction Key identifies the company used for each API interaction. Keep it confidential and store it securely.

Do not expose the key in publicly accessible browser JavaScript, mobile application source code or public repositories.

1. Configure your environment

Evaluation Services Interaction Keys can be obtained through the Portal; Qixol provides production keys. Keep each key confidential and use it only for its intended company and environment.

QixolPromo supports multiple companies within an organisation. Each company has its own configuration, products, promotions and Services Interaction Key.

Choose the environment that matches your integration stage:

Your integration should allow the API service URL and Services Interaction Key to be configured separately for each environment.

Do not assume that a development company can be accessed through the Production API services, or vice versa.

Production companies have IP restrictions enabled by default; Evaluation/Development companies are exempt. In the Portal use Configuration → Permitted IP Addresses, with separate Basket Service Access and Data Management Service Access lists. Updates may take up to 24 hours. Contact Qixol for exceptional exemptions.

2. Understand the Basket Evaluation API

Basket Evaluation allows your commerce application to submit a basket to QixolPromo and receive information about applicable promotions and discounts.

The two principal operations are:

Replace {companyKey} with the Services Interaction Key for the target company.

The full request URL consists of the appropriate environment's API base URL followed by the operation path.

For JSON requests, use:

Content-Type: application/json
Accept: application/json

3. Evaluate your first basket

API operation: Validate Basket (10300)

HTTP method: POST

Endpoint: /api/{companyKey}/basket/validate

Use this operation to submit a basket for promotion evaluation.

A basket normally contains a stable basket reference, sale date/time, one or more product lines and any additional information needed to determine promotion eligibility.

Example request

The following example shows a request for an Evaluation/Development company:

{
  "id": "ORDER-10001",
  "date": "2026-10-30T14:00:00Z",
  "confirmed": false,
  "currencycode": "GBP",
  "items": [
    {
      "id": 1,
      "productcode": "PRODUCT-001",
      "quantity": 2,
      "price": 10.00
    }
  ]
}

Replace PRODUCT-001 with a product code configured in your QixolPromo company.

The example uses an explicit UTC timestamp. Use the appropriate sale date/time for the transaction and keep it consistent when resubmitting the same basket.

Understanding the request

The API Reference documents additional properties, including customer identifiers, store, channel, delivery information, coupons, attributes and manual discounts.

Send the evaluation request

Save the example above as basket.json. Replace PRODUCT-001 with a product code in your evaluation company, set date to the sale date and time in UTC, and use an ID unique to the test basket. Keep confirmed set to false for this evaluation.

From the folder containing basket.json, run this command in Windows PowerShell. Replace YOUR_EVALUATION_KEY with the Services Interaction Key for your evaluation company. Keep the key out of shared scripts, screenshots and logs.

curl.exe -X POST "https://evaluation.qixolpromo.com/api/YOUR_EVALUATION_KEY/basket/validate" `
  -H "Content-Type: application/json" `
  -H "Accept: application/json" `
  --data-binary "@basket.json"

Check summary.result and summary.messages in the response. A request can return HTTP 200 and still report an application error.

Test a JSON request

1. Open Validate Basket (10300) and select application/json in the request body.
2. Choose Test Request. Use the evaluation server and enter your evaluation Services Interaction Key in companyKey.
3. Use a test basket ID and set the sale date and time. Replace the sample product code with one configured in your evaluation company and keep "confirmed": false. Check that Content-Type and Accept are both set to application/json, then send the request.
4. In the JSON response, check summary.result and review any entries in summary.messages. An HTTP 200 can still contain an application error. Select Download to save the original JSON response.

For the XML equivalent, see Test an XML request.

Important integration considerations

Maintain the same basket reference and sale date/time throughout the customer's shopping session.

The basket should reflect the current contents of the customer's order whenever it is submitted for evaluation.

Use confirmed: false while evaluating an uncompleted basket.

4. When should you validate a basket?

A commerce integration may submit the same basket to QixolPromo multiple times as the customer shops.

Typical integration points include:

Not every shopping-basket change requires an immediate API request. The appropriate frequency depends on how and when your application displays promotional prices and messages.

The Integration Best Practices guide explains these scenarios.

5. Interpret the basket evaluation response

The response contains the evaluation outcome and information about applicable promotions.

Do not rely solely on the HTTP status code to determine whether an API operation succeeded.

A processed request may return HTTP 200 even when QixolPromo reports an application-level failure.

Inspect the response summary.

The returned basket may differ from the submitted basket

Depending on the applicable promotions, QixolPromo may:

• Apply one or more discounts to an existing basket line.
• Split a line when only part of its quantity receives a discount.
• Add a free-gift line.
• Apply a delivery discount.
• Add custom attributes.
• Return information about coupon redemption or voucher issuance.
• Return applied promotion summaries and potentially missed promotions.

Your application should process the returned basket information rather than assuming that its structure will always match the original request.

For example, if a basket line containing three units is split because only one unit qualifies for a particular discount, your application may need to group the returned lines when presenting the basket to the customer.

See Integration Best Practices for guidance on processing returned baskets, and the API Reference for the full schema.

6. Validate a coupon code

API operation: Validate Coupon Code (10200)

HTTP method: POST

Endpoint: /api/{companyKey}/basket/validatecouponcode

Use this operation to check a coupon code and obtain its validation outcome.

Example request

{
  "code": "SAMPLE_CODE1"
}

Replace SAMPLE_CODE1 with a coupon code configured for your test company.

Understanding the request

A coupon may also be submitted as part of a basket evaluation.

Validating a coupon code independently does not necessarily establish that the associated promotion will apply to a particular basket. Promotion eligibility can depend on the basket contents and other conditions.

Inspect the returned application-level result and messages.

7. Understand unconfirmed and confirmed baskets

Unconfirmed basket

confirmed: false evaluates a basket without committing confirmed business effects. Use it for shopping and checkout previews.

Confirmed basket

Submit confirmed: true at the agreed completed-order stage (the original guidance recommends after payment); confirmation can record coupon utilisation, voucher issuance and promotion-use activity.

Reuse the same unique basket ID throughout the transaction, including modifications, resubmissions and confirmation. Reusing it prevents previously utilised coupons and issued vouchers from being processed twice for that basket, even after amendments. This does not guarantee full idempotency, and changes that remove qualification do not automatically reverse prior effects. See safe retries and confirmation guidance.

8. Handle errors and throttling

Inspect the HTTP outcome and application-level summary.result and summary.messages; an HTTP 200 can still contain an application failure. See Response Codes & Messages, including the CV validation family and TR999 throttling message.

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. These application-level limits do not apply to Production Basket requests. Export requests are limited to 5 calls per second. This limit applies to all companies. Pace requests and use a controlled retry after throttling. Import requests are queued for asynchronous processing and are not throttled.

For uncertain confirmed basket outcomes, reuse the same basket ID, reconcile the recorded effects, and avoid blind retries. See Integration Best Practices for detailed retry, access and import guidance.

9. Continue your integration

Once your initial requests are working, continue with the detailed documentation covering:

• Basket request properties and validation rules.
• Customer, store, channel and attribute information.
• Promotion eligibility and discount calculation.
• Processing split lines, free gifts and delivery discounts.
• Coupon validation and redemption.
• Confirmed basket handling.
• Errors, throttling and troubleshooting.

Further API documentation will cover Promotions, Products and Attributes, followed by Vouchers and Coupons.

.NET client library

For .NET integrations, Qixol provides the Qixol.Promo.Lib.Api package on NuGet. It supplies .NET classes for working with QixolPromo requests and responses.

The published package is version 3.8.0.6, updated on 19 July 2021. NuGet lists .NET Framework and .NET Standard 2.0 builds. Check the package's framework and dependency details against your application's target framework before adopting it.

Install this version with the .NET CLI or find Qixol.Promo.Lib.Api in Visual Studio's NuGet Package Manager.

dotnet add package Qixol.Promo.Lib.Api --version 3.8.0.6

The client wrapper source uses HTTPS POST requests with JSON or XML. It includes managers for Basket, Configuration, Import and Export services, with Evaluation, Production and custom endpoint options. Supply your confidential Services Interaction Key as the company key and follow the access and retry guidance in Integration Best Practices.

For WCF methods, service addresses and contract details, see WCF services and the operation-specific XML guides.

The interactive API Reference documents the REST operations. Use the WCF service contracts when configuring a WCF client.

Need assistance?

For environment access, integration guidance or technical questions, contact your QixolPromo representative.