024788: Ability to amend/cancel orders through webservices
Note: This functionality is not enabled by default. Please email development for more information
1. Overview
KCSL have added new webservices calls to enable the ability
to amend/cancel orders through Webservices.
2. Specification
Addition of new webservices calls to add the ability to amend/cancel orders through Webservices. “AmendOrder”, “CancelOrder”
Added extended Error handling:
· Mismatched order
· Order is not a web service order (reject ebay etc).
· Order not in an editable stage
· Order cannot be cancelled or edited.
· Order already being shipped / has been shipped / issued and cannot be cancelled or amended.
· Payment already processed (if the Preauth has been authorised the order cannot be edited or cancelled)
· Payment cannot be deleted - too much time has passed.
Notes/ caveats
· It is only possible to Amend / Cancel Web Service imported orders, orders from other channels like eBay etc cannot be edited and any requests to do so would be rejected.
· Payments having been processed beyond preauth would cause an abort.
· Refunding of cancelled orders is not in scope, the pre-auth on the orders would just be deleted.
· The call is restricted to orders placed within the last 48 hrs, if an order was older than this the amend attempts would be rejected.
· When running the amend function, it calls the
delete function and then calls the standard import orders function, effectively
replacing the old order with the new one. As a result, all order data must be
included in the amendment as no data is copied from the original except for the
sorder code and associated reference.
3. Configuration
An update and a changelog will be applied as part of this
development.
4. Usage
Below are the two Schemas for “OrderCancel” and “AmendOrder”.
Amend order largely follows the format of an Import.
<!--KhaosControl Standard XML Delete Sales Order -->
<DELETE_ORDERS>
<DELETE_ORDER>
<!--Comment: The code used to identify the order to be deleted-->
<!--Limit: 30 characters -->
<!-- THIS FIELD IS COMPULSORY -->
<CODE>SO123457</CODE>
<!--Comment: 0 = SORDER_ID, 1 = SORDER_CODE, 2 = ASSOCIATED_REF -->
<CODE_TYPE>0 </CODE_TYPE>
<!--Comment: The reason the sales order is being deleted-->
<!--Limit: 50 characters -->
<!-- THIS FIELD IS COMPULSORY -->
<REASON>Customer cancelled</REASON>
</DELETE_ORDER>
</DELETE_ORDERS>
Amend Order schema:
<!--KhaosControl Standard XML Import version 1.17 -->
<SALES_ORDERS>
<SALES_ORDER>
<CUSTOMER_DETAIL>
<!--Comment: -1 = True, 0 = False-->
<!--Comment: If false, update customer details from values (matching on COMPANY_CODE) instead of creating new-->
<!--If true, then a new customer is always created - no deduping is done -->
<!-- THIS FIELD IS COMPULSORY -->
<IS_NEW_CUSTOMER>-1</IS_NEW_CUSTOMER>
<COMPANY_CODE>KSD001</COMPANY_CODE>
<!--Comment: Specify a company class from KhaosControl, Only pre-existing classes will be mapped onto the customer record. Case Sensitive. -->
<COMPANY_CLASS>Internet</COMPANY_CLASS>
<!--Comment: Specify a company type from KhaosControl, Only pre-existing types will be mapped onto the customer record. Case Sensitive. -->
<COMPANY_TYPE>Others</COMPANY_TYPE>
<!-- If company name is left blank, KhaosControl will construct a name based on the contact details -->
<COMPANY_NAME>Keystone Software Development Ltd</COMPANY_NAME>
<!--Comment: Company Source Code. -->
<SOURCE_CODE>KC001</SOURCE_CODE>
<!--Comment: 1 - Our use and any 3rd parties, 2 - Our use and selected 3rd parties, 3 - Our use and no 3rd parties, 5 - Do not mail-->
<MAILING_STATUS>3</MAILING_STATUS>
<!--Comment: -1 = True, 0 = False-->
<OPTIN_NEWSLETTER>-1</OPTIN_NEWSLETTER>
<!-- VAT no. -->
<TAX_REFERENCE></TAX_REFERENCE>
<!-- User defined properties -->
<UDA>
<ADDITIONAL NAME="Security Question">Mother's Maiden Name</ADDITIONAL>
<ADDITIONAL NAME="Favourite Colour">Salmon Pink</ADDITIONAL>
</UDA>
<!-- Project 63 only - Gift Aid. Boolean field (-1, 0) This will apply to new customers only -->
<GIFT_AID>0</GIFT_AID>
<!-- In addresses, the ADDRESS1, POSTCODE, and contact (TITLE/FORENAME/SURNAME) fields should be set -->
<!-- Other fields are optional but are recommended, particularly COUNTRY_CODE -->
<ADDRESSES>
<INVADDR>
<IADDRESS1>Example address 1</IADDRESS1>
<IADDRESS2>Example address 2</IADDRESS2>
<IADDRESS3></IADDRESS3>
<ITOWN>Etown</ITOWN>
<ICOUNTY>County</ICOUNTY>
<IPOSTCODE>Pcode</IPOSTCODE>
<!--Comment: If both Country fields are blank the system default will be assumed ie. GBR, United Kingdom. Country Code is used if available. Country Name is only used if Code is blank. -->
<ICOUNTRY_CODE></ICOUNTRY_CODE>
<ICOUNTRY_NAME></ICOUNTRY_NAME>
<ITITLE>Mr</ITITLE>
<IFORENAME>Example Fname</IFORENAME>
<ISURNAME>Example Sname</ISURNAME>
<ITEL>TNumber</ITEL>
<IFAX></IFAX>
<IMOBILE></IMOBILE>
<IEMAIL></IEMAIL>
<!--Comment: contact.email_subscriber: Tickbox (-1 or 0) -->
<IEMAIL_SUBSCRIBER>-1</IEMAIL_SUBSCRIBER>
</INVADDR>
<!--Comment: If empty delivery address details then the system will use invoice address as above-->
<DELADDR>
<DADDRESS1></DADDRESS1>
<DADDRESS2></DADDRESS2>
<DADDRESS3></DADDRESS3>
<DTOWN></DTOWN>
<DCOUNTY></DCOUNTY>
<DPOSTCODE></DPOSTCODE>
<!--Comment: If both Country fields are blank the system default will be assumed ie. GBR, United Kingdom. Country Code is used if available. Country Name is only used if Code is blank. -->
<DCOUNTRY_CODE></DCOUNTRY_CODE>
<DCOUNTRY_NAME></DCOUNTRY_NAME>
<DTITLE></DTITLE>
<DFORENAME></DFORENAME>
<DSURNAME></DSURNAME>
<DTEL></DTEL>
<DFAX></DFAX>
<DMOBILE></DMOBILE>
<DEMAIL></DEMAIL>
<!--Comment: contact.email_subscriber: Tickbox -->
<DEMAIL_SUBSCRIBER>0</DEMAIL_SUBSCRIBER>
</DELADDR>
</ADDRESSES>
</CUSTOMER_DETAIL>
<PAYMENTS>
<PAYMENT_DETAIL>
<!--Payments for orders are not in KhaosControl system currency, they are assumed to be of the same currency as the order.-->
<PAYMENT_AMOUNT>56.99</PAYMENT_AMOUNT>
<!--Comment: 0 = Cash, 1 = Cheque, 2 = Credit Card, 3 = Account, 4 = Voucher-->
<PAYMENT_TYPE>2</PAYMENT_TYPE>
<CARD_TYPE>Visa</CARD_TYPE>
<!--Comment: Card number can also be used as voucher reference or cheque reference-->
<CARD_NUMBER></CARD_NUMBER>
<CARD_START></CARD_START>
<CARD_EXPIRE></CARD_EXPIRE>
<CARD_ISSUE></CARD_ISSUE>
<CARD_CV2></CARD_CV2>
<CARD_NAME></CARD_NAME>
<!--Comment: The Following fields can be used when payment (of type 2 only) has already been taken or pre-authed. -->
<!--Comment: If the AUTH_CODE is not empty the payment will be treated as PAID unless PREAUTH is TRUE. -->
<!--Comment: To process an authorisation following a preauth transaction, all information used must match that used in the preauth transaction.-->
<!--Comment: -1 = True, 0 = False.-->
<PREAUTH>0</PREAUTH>
<!--Comment: AUTH_CODE, e.g. Protx TxAuthNo (for Protx) -->
<AUTH_CODE></AUTH_CODE>
<!--Comment: TRANSACTION_ID, e.g. Protx VPSTxID (for Protx) or OrderID (HSBC XML/API) -->
<TRANSACTION_ID></TRANSACTION_ID>
<!--Comment: PREAUTH_REF, Reference used when Online transaction was made. ie. the Protx VendorTxCode. Needed to complete a preauth, or refund transaction through KhaosControl. -->
<PREAUTH_REF></PREAUTH_REF>
<!--Comment: SECURITY_REF, Protx SecurityKey Encryption reference. Needed to complete a preauth, or refund transaction through KhaosControl. -->
<SECURITY_REF></SECURITY_REF>
<!--Comment: SECURITY_COMMENT, (Optional) Protx AVSCV2, (Address and CV2 matched / Address match only / CV2 match only etc. -->
<SECURITY_COMMENT></SECURITY_COMMENT>
<!--Comment: ACCOUNT_NUMBER, (Optional) Number of account in KhaosControl to charge card against, if multiple accounts are set up -->
<ACCOUNT_NUMBER></ACCOUNT_NUMBER>
<!-- To successfully import a preauth the following fields are needed:
From Protx:
-Preauth must be -1
-AuthCode, Transaction_ID, Preauth_Ref and Security_Ref must be non-blank and contain the details returned by Protx from the preauth
-Security_Comment should be filled in with AAV results if possible (not required)
From HSBC XML/API:
-Preauth must be -1
-Transaction_ID should have the order ID from the original preauth transaction - the other fields are not required for HSBC
-->
</PAYMENT_DETAIL>
</PAYMENTS>
<ORDER_HEADER>
<!--Comment: Date format: yyyy-mm-dd or yyyy-mm-dd hh:mm:ss, other date formats SHOULD NOT BE USED -->
<ORDER_DATE>2024-01-20</ORDER_DATE>
<DELIVERY_DATE>2024-01-21 10:11:22</DELIVERY_DATE>
<!--Comment: Used to check against order total calculated in Khaos Control-->
<ORDER_AMOUNT>56.99</ORDER_AMOUNT>
<!--Comment: If ORDER_CURRENCY_CODE is blank the currency will default to the Khaos Control System currency (normally GBP)-->
<!--Please specify the 3 character Currency Code, associated with the currency in Khaos Control (System Data/Currencies) ie. GBP / USD / EUR etc.-->
<ORDER_CURRENCY_CODE>GBP</ORDER_CURRENCY_CODE>
<!--Comment: Usually the web generated order reference. -->
<!-- THIS FIELD IS COMPULSORY -->
<!-- This should be unique across all orders: it is used to make sure the same order is not imported twice -->
<ASSOCIATED_REF>DK07151555O</ASSOCIATED_REF>
<!--Comment: Could be used to record comments from customers or to describe special delivery instructions, this will appear on KhaosControl Delivery Note Documentation.-->
<ORDER_NOTE></ORDER_NOTE>
<!--Comment: Could be used to record comments from customers or to describe special delivery instructions, this will appear on KhaosControl Invoice Documentation.-->
<INVOICE_NOTE></INVOICE_NOTE>
<!--Comment: Use net & tax (VAT) OR grs. If grs is used amount is assumed to be VATable-->
<!--Specify -1 to disable delivery -->
<!--Any other value for delivery (inc. zero) is saved against the order as the delivery charge -->
<!--If the tags are blank/missing then the system will calculate its own delivery charges -->
<DELIVERY_NET>0</DELIVERY_NET>
<DELIVERY_TAX>0</DELIVERY_TAX>
<DELIVERY_GRS>0</DELIVERY_GRS>
<!--Comment: Specify either courier code OR courier description. Code is preferred (more likely to be unique) -->
<COURIER_CODE></COURIER_CODE>
<COURIER_DESC></COURIER_DESC>
<!--Comment: Specify a promotion code from KhaosControl, Only pre-existing codes will be mapped onto the order. Discounts will be applied after order import, so any prices / order totals should be original prices prior to any discounts or reductions.-->
<KEYCODE_CODE></KEYCODE_CODE>
<!--Comment: Specify a source code from KhaosControl, Only pre-existing codes will be mapped onto the order. Case Sensitive. -->
<SALES_SOURCE>INTERNET</SALES_SOURCE>
<!--Comment: Courier note is actually recorded against the DELIVERY address, overwriting any notes already present -->
<COURIER_NOTE></COURIER_NOTE>
<!--Comment: Select a priority to record against the invoice (set up in KhaosControl / SystemData) -->
<!--Comment: Invoice priority matches on description only at the moment, not 'code' or 'mark' -->
<INV_PRIORITY></INV_PRIORITY>
<!-- Project 63 only - Gift Aid. Boolean field (-1, 0). This will override the customers default. -->
<GIFT_AID>0</GIFT_AID>
<!-- Custom properties - only set after discussion with Keystone Software -->
<CUSTOM>
<CUSTOM_PROPERTY NAME="ORDER_WEIGHT">1000</CUSTOM_PROPERTY>
<CUSTOM_PROPERTY NAME="INFLATE_PRICES">-1</CUSTOM_PROPERTY>
</CUSTOM>
</ORDER_HEADER>
<ORDER_ITEMS>
<ORDER_ITEM>
<!-- This field contains a stock code or other_ref value - see MAPPING_TYPE field -->
<!-- THIS FIELD IS COMPULSORY -->
<STOCK_CODE>HL0453</STOCK_CODE>
<!--Comment: 1 = Above stock code relates to the Khaos Control "stock code" value, 2 = Stock code relates to the Khaos Control "other ref" value, 3 = External mapping file used for stock code resolution, 4 = Match on Stock Description (not recommended!) -->
<!-- THIS FIELD IS COMPULSORY -->
<MAPPING_TYPE>1</MAPPING_TYPE>
<!-- If no description specified, the system will use the default description against the stock item. -->
<!-- Recommended to be specified so description on printouts matches website description -->
<STOCK_DESC>LARGE DISPLAY CABINET</STOCK_DESC>
<!--Comment: Can be used as a comment or note against each order line-->
<EXTENDED_DESC>Please fit with brass handles.</EXTENDED_DESC>
<ORDER_QTY>1</ORDER_QTY>
<!--Comment: Use either net OR grs. If both are used only net will be actioned-->
<PRICE_NET>12.34</PRICE_NET>
<PRICE_GRS>56.99</PRICE_GRS>
<!--Comment: 1 - Standard (17.5%), 2 - Zero, 4 - Reduced (15%), >4 user defined-->
<!--Comment: Do not include a tax rate directly (eg 17.5), you must use the codes mentioned above (1, 2, ...) -->
<TAX_RATE>1</TAX_RATE>
<!--Comment: Optional fields that are used in mapping Size, Colour, Style situations-->
<OPTION_REF1>OAK</OPTION_REF1>
<OPTION_REF2>PANELED</OPTION_REF2>
<OPTION_REF3></OPTION_REF3>
</ORDER_ITEM>
<ORDER_ITEM>
<STOCK_CODE>HL0454</STOCK_CODE>
<MAPPING_TYPE>1</MAPPING_TYPE>
<STOCK_DESC>LARGE DISPLAY CABINET</STOCK_DESC>
<ORDER_QTY>1</ORDER_QTY>
<PRICE_NET>12.34</PRICE_NET>
<TAX_RATE>1</TAX_RATE>
</ORDER_ITEM>
</ORDER_ITEMS>
</SALES_ORDER>
</SALES_ORDERS>