Integrating with Qixol Promo
OverviewQixol Promo is designed for quick and complete integration from virtually any platform. Access to the Promo API services is via REST or WCF. If you are integrating from a platform authored in Microsoft .NET, there is also a .NET assembly available to further simplify the integration process (see section below.)
This article is intended to provide details on how to integrate with Promo. To fully understand the data that needs to be submitted to Promo, it is recommended that an evaluation company be created in Promo and a full review of the product be completed in order to ensure key concepts around basket, product and attribute management are understood.
AttributesBefore integrating with Promo, it is important to understand the role of attributes, in order to ensure that all required Product and Basket level attributes are defined, and Promo has the full range of values for those attributes. The attributes that will be defined for both Products and Baskets will be specific to the implementation.
Basket Attribute example: For an integration with a Point-of-Sale terminal, it may be necessary to provide a flag indicating whether the basket is submitted with a validated STAFF identification number. To cope with this, a new Basket Attribute would be created in the Promo Administration Portal, with values assigned to it of 'Yes' and 'No' (or other values as required - these values can be managed using the Promo API). This attribute could then be utilized when creating promotions, by adding a Basket Level Criteria to the promotion, to indicate that it can only be applied when the value for this attribute received with baskets is set to 'Yes' or 'No'. All baskets submitted from the integrating Point-of-Sale terminal(s) would be expected to provide the attribute with baskets.
Product Attribute example: For an integration with a website, it may be necessary to provide details with each product, on the category(s) within the website where the product is displayed. For example for a fashion website, this could include Shoes which are displayed in the 'Shoes' category, but also in the 'Complete Outfits' category. The new product attribute can optionally be created within the Promo Administration Portal, and the values for that attribute are submitted with products when they are created or amended. Where a value is submitted for a product attribute that is not found, that attribute will be automatically created. Product attributes can then be used when creating promotions to help with identifying products, by adding one or more Product Attribute Criteria to the promotion. When a product is included as a line in the basket, its attributes are looked up and compared against the criteria defined within each promotion to see if it should be included.
Before integrating with Promo, it is important to ensure that supplied Product data has all required attributes that will be needed to restrict when a promotion should be applied, and that all required Basket Attributes and their values have been created.
Using the services
All interactions with Promo are managed within the context of a company. When you register with Promo, a company is created for you, within which all promotions and other product/attributes data resides. Each company is assigned a unique key, and this key must be provided with all interactions to the service APIs. When using the REST services, the company key must be included in the Url of the service method. If using WCF services the company key must be suppled in the XML request document. To see your assigned company key, please navigate to Configuration within the Administration Portal, and then select Manage Company.
All information passed to the Promo services must be encapsulated in Json or XML complying with the defined schema. Where dates are passed these should be in Universal Time Coordinated (UTC), and can include a timezone if applicable. For both Json and XML documents the date and time format must adhere to XML standards, as per this w3schools article.
CurrenciesCurrency values within data submitted to Promo should never include a currency symbol, and should use a decimal point for the decimal mark. A maximum of two decimal places should be used for currency values.
When to use the ServicesIt is recommended that the following areas of integration be managed using a periodic approach (for example as a nightly scheduled activity, or more frequently if required):
- Product information -push to Import Services
- Basket attribute values -push to Import Services
- Campaign/Coupon code updates -pull from Export Services
- Campaign/Coupon code updates -push to Import Services
- Promotions available for day (not line-level) -pull from Export Services
- Promotions available for day (line-level) -pull from Export Services
When a basket (or transaction) is being created or completed, the following real-time services can be used:
- Basket Validation -push to Basket Services
Note: flags passed with the basket will indicate to Promo whether the basket or order is being completed (in which case any Campaign/Coupon codes to be issued or redeemed will be confirmed by Promo) and whether to return details on missed promotions which may typically not be required until entering the check-out phase of the order.
- Campaign/Coupon code Validation -pull from Basket Services
.NET Framework and .NET Core 2.0If the integrating system is authored using Microsoft .NET, it is recommended that you use the Qixol Promo Api Library. This can be added to your project or solution, when using Microsoft Visual Studio, by searching for Qixol Promo in the NuGet Package Manager using nuget.org as the package source, then clicking Install. The assembly provides an object model for all interactions with Qixol Promo.