Front-end API

The Shift4Shop front-end API exposes some useful resources to web developers. With these methods, web developers can retrieve product information, as well as add items to a customer's shopping cart, view a list of all items in the cart and adjust quantities. The front-end API responds to properly formatted HTTP requests with the response body containing the corresponding JSON. The request endpoint URL is yourdomain.com/frontapi.asp with some additional URL query parameters. The parameters needed to format a request will vary based on the module the request is targeting. The modules available are listed below.

Products:

Parameters:

  • module: (required and set to: module=products)
  • productid: Use this parameter when you want to receive a single product’s details.
  • categoryid: Use the categoryid parameter when you want to filter the results by category.
  • limit: Using the limit and offset parameters, a range of products can be received by sending an HTTP GET request to http://yourdomain.com/frontapi.asp?module=products&limit=10&offset=100 (the limit parameter takes a maximum of 200).
  • offset: see above

To receive information on products, an HTTP GET request should be sent to http://yourdomain.com/frontapi.asp?module=products?productid=123 (where ‘123’ is the catalogid value for the product). Below is an example JSON response:

Sample response
{
    "CatalogID":"123",
    "Name":"Sample Product",
    "SKU":"SAMPLE123",
    "ThumbnailFile":"assets\/images\/products\/sample_thumb.jpg",
    "Stock":"10",
    "Price":"9.99",
    "MainImageFile":"assets\/images\/products\/sample.jpg",
    "ProductLink":"http:\/\/yourdomain.com\/sample-product.html",
    "InventoryControl":"2",
    "InventoryControlGlobal":"2",
    "OptionSetList":"[{\"OptionSetId\":\"33\",\"OptionSetName\":\"Size\",\"OptionSorting\":\"0\",\"OptionRequired\":\"0\",\"OptionType\":\"Dropdown\",\"OptionURL\":\"http:\/\/www.3dcart.com\",\"OptionAdditionalInformation\":\"\",\"OptionSizeLimit\":\"0\",\"OptionList\":[{\"OptionID\":\"61\",\"OptionName\":\"Small \u00B0\",\"OptionSelected\":\"0\",\"OptionHide\":\"0\",\"OptionValue\":\"1\",\"OptionPartNumber\":\"\",\"OptionSorting\":\"0\",\"OptionImagePath\":\"\",\"OptionBundleCatalogId\":\"0\",\"OptionBundleQuantity\":\"1\"},{\"OptionID\":\"62\",\"OptionName\":\"Medium\",\"OptionSelected\":\"0\",\"OptionHide\":\"0\",\"OptionValue\":\"5\",\"OptionPartNumber\":\"\",\"OptionSorting\":\"1\",\"OptionImagePath\":\"\",\"OptionBundleCatalogId\":\"0\",\"OptionBundleQuantity\":\"1\"},{\"OptionID\":\"63\",\"OptionName\":\"Large\",\"OptionSelected\":\"0\",\"OptionHide\":\"0\",\"OptionValue\":\"10\",\"OptionPartNumber\":\"\",\"OptionSorting\":\"2\",\"OptionImagePath\":\"\",\"OptionBundleCatalogId\":\"0\",\"OptionBundleQuantity\":\"1\"}]}]"
}

Cart:

Parameters:

  • module: (required: module=cart)
  • incompleteorderid: (required) The incompleteorderid value comes from the incompleteorderid cookie in the customer’s browser and is how you identify which cart’s information you’re requesting.

To view the contents of a cart, an HTTP GET request can be sent to http://yourdomain.com//frontapi.asp?module=cart&incompleteorderid=mnfHbNF3TGmyNrv739

Below is an example JSON response:

Sample response
{
    "errorurl":"",
    "redirecturl":"",
    "AddedToCart":1,
    "catalogid":0,
    "orderid":739,
    "LastItemAdded":[
        {
            "catalogid":129405,
            "thumbnail":null,
            "name":"Sample Product",
            "qty":1,
            "itemname":"Sample Product",
            "itemid":"129405",
            "orderitemid":1138,
            "optionids":",328",
            "price":9.99,
            "lineitemprice":9.99
        }
    ],
    "ItemsInCart":[
        {
            "catalogid":129405,
            "thumbnail":null,
            "name":"Sample Product",
            "qty":1,
            "itemname":"Sample Product",
            "itemid":"129405",
            "orderitemid":1138,
            "optionids":",328",
            "price":9.99,
            "lineitemprice":9.99
        }
    ],
    "orderFromWidget":"o4Yz6hDrXD8=",
    "incompleteorderid":"mnfHbNF3TGmyNrv739",
    "hk":"3Uh2jYL1CZkAdOoYn9Qm2mZt0LLdeNt+",
    "affiliate":""
}

Add to Cart:

Parameters:

  • module: (required)
  • form data: (not a URL parameter) The form data is appended to POST requests (see below for examples).
  • incompleteorderid: (required when updating an existing cart) The incompleteorderid value comes from the incompleteorderid cookie in the customer’s browser and is how you identify which cart’s information you’re requesting when adding an item to an existing cart. If you are creating a new cart this parameter should be omitted.
  • hk: (required when updating an existing cart) The hk value is received in all responses from the Cart and Add to Cart modules. This value needs to be sent in requests to update an existing cart. If you are creating a new cart this parameter should be omitted.

In order to add items to a customer’s cart, a POST request containing multipart form data can be sent

Javascript:

Example using javascript
function add_to_cart(intCatalogID, strSKU, intCategoryID, intPrice, intQuantity, intAffiliateID) {
    var formData = new FormData();
    formData.append('item_id', intCatalogID);
    formData.append('itemid', strSKU);
    formData.append('category_id', intCategoryID);
    formData.append('std_price', intPrice);
    formData.append('qty-0', intQuantity);
    formData.append('option-33-123', '62');// The key is the 'name' attribute of the option's HTML input tag and the value is the option selected. Repeat for all options.
  
    var qryStr = '?module=addcart;
  
    jQuery.ajax({
        url: 'http://yourdomain.com/frontapi.asp' + qryStr,
        dataType: 'json',
        type: 'POST',
        cache: false,
        contentType: false,
        processData: false,
        data: formData,
        success: function (data) {
            //Do stuff
        } else {
            //handle error
        }
    }
}

PHP

Example using PHP
$post = [
    'item_id'=>'123',
    'itemid'=>'SAMPLE',
    'category_id'=>'42',
    'std_price'=>'24.99',
    'intQuantity'=>'1',
    'option-33-123'=>'62'
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://yourdomain.com/frontapi.asp?module=addcart');
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);//must be passed as an array
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$jsonResponse = curl_exec($ch);

Update item quantities:

  • module: (required: module=updateqty)
  • incompleteorderid: (required) The incompleteorderid value comes from the incompleteorderid cookie in the customer’s browser and is how you identify which cart’s information you’re requesting.
  • hk: (required) The hk value is received in all responses from the Cart and Add to Cart modules. This value needs to be sent in requests to update an existing cart.
  • qtyX: (required. ‘X’ is a 0 indexed value representing the items row/position within the cart).
  • colidX: (required. This is the ‘orderitemid’ value seen in addcart responses. The ‘X’ is a 0 indexed value representing the items row/position within the cart).

To update the quantity of an item in the cart, the request is slightly different. A POST request is sent to http://yourdomain.com/frontapi.asp without any query parameters. The parameters will be sent as a application/x-www-form-urlencoded string.

Javascript:

Example using javascript
function updateQty(intOrderItemID) {   
    // intOrderItemID is the 'orderitemid' value from a cart module request
    // The qtyX parameter (where x is a number between 0 and 99) is a zero-indexed parameter representing the row of the items in cart.
    // The colidX parameter (where x is a number between 0 and 99) is a zero-indexed parameter representing the row of the items in cart.
    var dataq = 'module=updateqty&incompleteorderid=' + getCookie('incompleteorderid') + '&qty0=2&colid0='+intOrderItemID;
    jQuery.ajax({
        url: 'http://yourdomain.com/frontapi.asp',
        dataType: 'text',
        type: 'POST',
        cache: false,
        async: true,
        data: dataq,
        success: function () {
            // do stuff
        },
        error: function (objError) {
            //handle error
        }
    });
}

PHP

Example using PHP
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://yourdomain.com/frontapi.asp');
curl_setopt($ch, CURLOPT_POSTFIELDS, 'module=updateqty&incompleteorderid='.$_COOKIE'incompleteorderid'.'&qty0=2&colid0=1133');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$jsonResponse = curl_exec($ch);

Errors:

HTTP Response Code
Reason
404
The requested item (product or cart) was not found. In the case of products, this error message is also received when the product is found, however, it is out of stock, hidden, not for sale, or otherwise in a state where it is not visible to the public (e.g. only available at specific price levels, restricted to a specific customer group, etc.).
400
The request was invalid. For example, the JSON was not formatted properly, or an invalid parameter value was sent.