How to Use the X-Cart Shopping Cart API

Introduction

X-Cart is a turnkey, template-driven shopping cart solution for merchants looking to provide online customers with both a desktop and mobile shopping experience. In this tutorial, you'll learn to use X-Cart's REST APITrack this API to exchange data with the X-Cart database without the need for direct access to the underlying database server. This tutorial assumes that you've established (or are beginning to establish) an online storefront with X-Cart.com.

Through the API, merchants can build their own solutions that interact with the X-Cart backend or integrate X-Cart with other existing business systems. Because of the way APIs serve as a means of decoupling front from back ends which in turn results in programming language independence, the X-Cart API also enables merchants to build solutions in languages of their choice.

The API is available as a free extension. It is provided and supported by the X-Cart team itself, hence it's an official API from X-Cart. It can be used for all editions of X-Cart 5, including the free one.

Please keep in mind, this guide is based on the X-Cart v5.3.1 API. Some models (more on what a model is later) and their APIs may change over the course of time, so there's no guarantee that the code samples below will work for all the upcoming versions, but they will at least give you an idea in what direction to move.

Part One: Much Theory

Install and setup

Find the REST API module right within the administrative back end of your store.

Find the REST API module right within the administrative back end of your store.

Check Install under the module icon, press the Install Modules button and the extension will be installed in the background. Once the installation is finished, you'll be redirected to the Recently Installed Modules page and the Settings link will appear next to the module icon. Click on it to see the following page:

 Install Modules

Specify which one of the keys you need (or both, if necessary):

  • API key (read/write) allows an external application to have full access to X-Cart data (both reading and writing)
  • API key (only read) allows an external application to read data, but not to modify it

The REST API allows the developer to operate with all your store's data. An external script with a read-and-write API key will be able to fetch, edit, and remove any type of data. This is why you should be very selective giving out the API keys to other people or companies, and if read-only access is sufficient for some applications, use the read-only key rather than read-and-write one.

Test It to Make Sure You're All Set

http://<X-CART-PATH>/admin.php?target=RESTAPI&_key=<YOUR-API-KEY>&_path=product/1 where <MY-XCART-PATH> is the path to your X-Cart store

<YOUR-API-KEY> is your actual REST API key product/1 is the ID of a product that does exist in your store

If a product with ID=1 exists in your database and the URL and key are correct, this API call will return the product info in JSON format. It will be something like this:

{
   "freeShip": false,
   "freightFixedFee": 0,
   "isCustomerAttachmentsAvailable": false,
   "isCustomerAttachmentsRequired": false,
   "participateSale": false,
   "discountType": "sale_price",
   "salePriceValue": 0,
   "pinCodesEnabled": false,
   "autoPinCodes": false,
   "marketPrice": 0,
   "ogMeta": "",
   "useCustomOG": false,
   "product_id": 1,
   "price": 19.99,
   "sku": "10001",
   "enabled": true,
   "weight": 0.32,
   "useSeparateBox": false,
   "boxWidth": 0,
   "boxLength": 0,
   "boxHeight": 0,
   "itemsPerBox": 1,
   "free_shipping": false,
   "taxable": true,
   "javascript": "",
   "arrivalDate": 1424506256,
   "date": 1437466241,
   "updateDate": 1437466242,
   "needProcess": false,
   "attrSepTab": true,
   "metaDescType": "A",
   "upsellingProducts": [],
   "upsellingParentProducts": [],
   "reviews": [],
   "variants": [],
   "variantsAttributes": [],
   "vendor": null,
   "tabs": [],
   "views_stats": [],
   "purchase_stats": [],
   "pinCodes": [],
   "attachments": [],
   "featuredProducts": [],
   "categoryProducts": [
     {
       "id": 1,
       "orderby": 0
     }
   ],
   "order_items": [
     {
       "xpcFakeItem": false,
       "item_id": 10,
       "name": "Planet Express Babydoll",
       "sku": "10001",
       "price": 19.99,
       "itemNetPrice": 19.99,
       "discountedSubtotal": 17.979,
       "amount": 1,
       "total": 19.99,
       "subtotal": 19.99
     }
   ],
   "images": [
     {
       "orderby": -10,
       "alt": "Planet Express Babydoll",
       "s3icons": [],
       "width": 500,
       "height": 494,
       "hash": null,
       "needProcess": true,
       "id": 1,
       "path": "demo_p4003.jpeg",
       "fileName": "",
       "mime": "image\/jpeg",
       "storageType": "r",
       "size": 29749,
       "date": 1280310731
     }
   ],
   "inventory": {
     "inventoryId": 1,
     "enabled": true,
     "amount": 50,
     "lowLimitEnabled": true,
     "lowLimitAmount": 10
   },
   "productClass": {
     "id": 1,
     "position": 0
   },
   "taxClass": null,
   "attributes": [],
   "attributeValueC": [],
   "attributeValueT": [],
   "attributeValueS": [
     {
       "priceModifier": 0,
       "priceModifierType": "a",
       "weightModifier": 0,
       "weightModifierType": "a",
       "defaultValue": false,
       "id": 1
     },
     {
       "priceModifier": 0,
       "priceModifierType": "a",
       "weightModifier": 0,
       "weightModifierType": "a",
       "defaultValue": false,
       "id": 2
     },
     {
       "priceModifier": 0,
       "priceModifierType": "a",
       "weightModifier": 0,
       "weightModifierType": "a",
       "defaultValue": false,
       "id": 3
     },
     {
       "priceModifier": 0,
       "priceModifierType": "a",
       "weightModifier": 0,
       "weightModifierType": "a",
       "defaultValue": false,
       "id": 4
     },
     {
       "priceModifier": 0,
       "priceModifierType": "a",
       "weightModifier": 0,
       "weightModifierType": "a",
       "defaultValue": false,
       "id": 244
     }
   ],
   "quickData": [
     {
       "id": 13,
       "price": 19.99
     },
     {
       "id": 14,
       "price": 19.99
     }
   ],
   "memberships": [],
   "cleanURLs": [
     {
       "id": 1,
       "cleanURL": "planet-express-babydoll.html"
     }
   ],
   "translations": [
     {
       "name": "Planet Express Babydoll",
       "description": "",
       "briefDescription": "",
       "metaTags": "",
       "metaDesc": "",
       "metaTitle": "",
       "label_id": 1,
       "code": "en"
     },
     {
       "name": "\u0424\u0443\u0442\u0431\u043e\u043b\u043a\u0430 \"Planet Express Babydoll\"",
       "description": "",
       "briefDescription": "",
       "metaTags": "",
       "metaDesc": "",
       "metaTitle": "",
       "label_id": 46,
       "code": "ru"
     }
   ]
 }

REST API Output Options

Output is always in the UTF-8 charset.

Depending on the Accept HTTP header, the module will output data in JSON (default value) or in XML (in this case you must specify the Accept header as application/xml).

Example Header

Output always comes with the following HTTP headers:

  • Content-Type
  • Content-Length
  • Content-MD5
  • ETag
  • Last-Modified
  • Accept-Ranges

The REST API will return the HTTP response code 304 (Not Modified) if the request comes with the header If-Modified-Since or If-None-Match and the data has not been updated. Hence the ETag and Last-Modified headers for it will remain the same.

Working with REST API Using a PHP Client

If making requests via pure cURL and then parsing the results manually is not what you're after, feel free to use our PHP Software Development Kit (SDK), which is built upon the Guzzle lib for Linux. In order to prepare your environment, you should do the following:

Using the Composer Dependency Management Utility for PHP, go to the Linux command line interface and install Guzzle in the folder where your scripts that work with the REST API are located.

Ksenia Emelyanova I'm a copywriter. I started my journey with X-Cart in 2009 as a customer support assistant, went on to work as a Project manager in the Custom Development team to discover the needs of e-merchants and deliver the projects that meet their needs. This experience gave me deep understanding of how things work from both a developer's side and a user's point of view, and it really helps in creating the articles with love and care. Apart from eCommerce, I'm a loving wife and mother, yogi and aerial performer.
 

Comments

Comments(2)

Adrienne R. Moore

Hey there! Nice article, Thanks for sharing this information. X-Cart is a wonderful platform but I don’t undestand why much information is not available on the internet regarding this shopping cart Development. I m glad that found your blog. Keep posting! :-)

Adrienne R. Moore

X-Cart team

Hi Adrienne,

 Thank you for your feedback. Happy to hear that my work was not in vain.

Here you can find all the docs regarding the X-Cart development: https://www.x-cart.com/help.html

Also, we have a dedicated  engineer who works with X-Cart developers directy: If the question of theirs is rather general, he creates another article for a developer portal, if it's specific, he just helps to sort this question out directly, via email or skype. I hope you will not face any trouble developing for X-Cart, but it you will, please contact X-Cart team, and your questions will be dispatched to the right person.

Kind regards