MMS/Click X-Cart Interface

MMS/Click runs directly against the X-Cart MySQL tables, so there is no customization of the X-Cart source code needed.

MMS/Click runs every 15 minutes. First all qualifying X-Cart orders are Uploaded to MMS for shipping, then the web portion of the MMS inventory is Downloaded to the X-Cart to reflect any new web items and changes to inventory.

X-Cart Orders.status Codes

These Order Status Codes are from the X-Cart Reference Manual:

INot FinishedPayment not yet processed.
FFailedPayment cannot be processed.
QQueuedWaiting for manual payment processing.
PProcessedPayment has been received.
CCompletePayment received and order uploaded to MMS.
BBackorderedPayment returned?
DDeclinedManually assigned equivalent of Failed.

Order Upload Lifecycle

The default X-Cart mode is to capture credit cart information for manual processing, so the default new order status is Queued, "waiting for manual processing".

When X-Cart is configured to process credit cards during the order process new orders get a status of Processed, "paid for".

When the configuration variable $mmsc_send_queued is set to 1 (the default) the order upload process will upload both Queued and Processed orders. If $mmsc_send_queued is set 0 only Processed orders will be uploaded.

When an order is uploaded from X-Cart to MMS without errors the order status is set to Complete because X-Cart is finished with the order.

For Queued orders the order Tracking field is set to "MMS Order #123". For Processed orders the order Tracking field is set to "MMS Paid #123".

If an upload error occurs the order status does not change but the Tracking field is set to "MMS Error ...". See below for details.

These messages are also added to the orders.notes field along with the data and time to keep a history of upload attempts. In pseudocode:

foreach order where
    (
          order.status == 'P' or 
        ( order.status == 'Q' and mmsc_send_queued )
    )
{
    if ( upload_success( order ) )
    {
        if ( order.status == 'P' )
        {
            order.tracking = "MMS Paid #8785";
        }
        else
        {
            order.tracking = "MMS Order #8785";
        }
        order.status       = 'C';  // Complete on X-Cart.
    }
    else 
    {
        order.tracking     = "MMS Error Invalid Item 564";
    }
    order.notes           .= "2004.11.20 12:49:23 " . order.tracking;
}

Order Upload Error Messages

If the MMS WEB_DEFL view has not been set up the upload process will report "Fatal MMS WEB_DEFL not set up" and quit before any orders are uploaded.

Other errors occur on a per order basis. When an error is detected in an order the order.tracking and order notes fields are updated and the order upload process attempts to upload more orders.

X-Cart order items refer to the X-Cart products table. The products.productcode (SKU) field holds the INV_IVEN.inv_number. If an order item productcode holds an invalid inv_number an error of "Invalid Item 1234" will be returned.

X-Cart product tax codes are (potentially) translated through the $mmsc_tax_2_mms hash array. If a (translated) tax code does not exist in the POS_SPCL.spcl_code an error of "No Taxc Spcl Srvc 'GST'" will be returned.

When an upload fails the procedure is to correct the problem and manually clear out the orders.tracking field so that the next Order Upload Process will try again.

You can view and update the orders.tracking and orders.notes fields using the http://host-name/xcart-url/admin/ interface.

Inventory Download Lifecycle

Inventory items in the MMS CIN_IVEN table where the "comment_1" field begins with "WEB" are downloaded from MMS to X-Cart and marked as "for sale":

CIN_IVEN FieldX_Cart Field(s)Comment
inv_numberproducts.productcodeX-Cart SKU = MMS id.
model_nameproducts.product
products.desc
Product name.
prd_typeproducts_categories.categoryidProduct category.
retailproducts.list_priceList price.
sellingpricing.priceSelling price.
weightproducts.weightShipping weight.
available_qty_for_web_salesproducts.availCalculated field.

The model_name on MMS is all uppercase. When an inventory item is first downloaded from MMS to X-Cart the model_name is lowercased and the first letter of each word is uppercased. This is inserted into both the product name and the description fields. After the initial download no further changes to those fields are made to allow the X-Cart administrator to enter more consumer friendly text.

The retail, selling, weight, and available_qty_for_web_sales values are all updated during each download cycle. The special available_qty_for_web_sales field adjustments are explained in the next section.

When an MMS inventory item's comment_1 field no longer begins with "WEB", the X-Cart products.forsale field is updated to "N" so that item is no longer for sale and will not show up in new orders.

Pending Order Inventory Accounting

X-Cart considers the items in an order to be "reserved" from inventory and thus have been deducted from the products.avail count. The exceptions are "Failed" and "Declined" orders. Failed and Declined order items have not been deducted from products.avail.

The MMS database is only aware of orders which have been uploaded and thus have an orders.status of "Complete". The items from those orders have been deducted from both the X-Cart inventory and the MMS inventory count.

This leaves orders with statuses "I", "Q", "P" and "B" which are "Pending" in the sense that X-Cart considers them to be deducted against inventory, but MMS does not.

The Inventory Download process needs to account for Pending Order items and compensate for this difference while updating the X-Cart products.avail counts from the MMS inventory counts.

It is generally advisable to keep the number of Pending Orders to a minimum.

Administrative Tasks

Each customer will need someone to watch the status of their shopping cart and resolve any problems that arise.

MMS/Click should run every 15 minutes. Whenever it runs it leaves a status message in two places on the X-Cart admin interface.

Look at http://host-name/xcart-url/admin/home.php in the "Orders Info" section. You should see something like this:

MMS/Click 2004.11.05 15:09:35
9 pending orders by status: I=2 Q=3 P=4 

http://host-name/xcart-url/admin/orders.php will show the same message.

Make sure that MMS/Click is running every 15 minutes, and resolve any errors in Pending Orders. In the above example you will want to select each of the "Incomplete", "Queued" and "Processed" orders and look at the orders.tracking fields for error messages.

If there are problems be sure to look at the log files.