Products and Articles

Make sure you familiarize yourself with the other important concepts of our API:
Prices and Quantities, Sync Markers
After taking the time to understand these concepts, you will much better understand the basics of our API.

Introduction

Before you get started with products, be aware that there is an important distinction to remember.

  1. Products: This is simply a way to group articles.
  2. Articles: These are the actual articles that you display in your application, put in your orders, retrieve the stock information of, etc.

When you are working with products that have multiple sizes and colours, these separate sizes and colours will be separate articles grouped under one product.

Contents

getProducts Retrieving all products

Use this function to get a complete or partial list of all available products.
You can use the array articleNumbers to limit the results to specific articles.
You can specify a syncMarker to limit the results to changed articles since a specific moment.
Learn more about Sync Markers here.

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<?php
 
require_once('Mplusqapiclient.php');
 
$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.
 
$articleNumbers = array(); // specificy which articles to retrieve
$groupNumbers = array(); // specificy which groups to retrieve
$pluNumbers = array(); // specificy which PLU numbers to retrieve
$changedSinceTimestamp = null;
$changedSinceBranchNumber = null;
$syncMarker = 1; // syncMarker is a better way of synchronizing than changedSinceTimestamp/BranchNumber
$onlyWebshop = false; // If only articles marked as webshoparticles need to be retrieved
$onlyActive  = false; // Only retrieve active articles
 
// Then we call the getProducts() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($products = $mplusqapiclient->getProducts($articleNumbers, $groupNumbers, $pluNumbers, $changedSinceTimestamp, $changedSinceBranchNumber, $syncMarker, $onlyWebshop, $onlyActive))) {
    // Success, we show the amount of found products
    exit(sprintf('Found %d products.', count($products)));
  } else {
    exit('Failure while getting products.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

The result of getProducts can contain a sortOrderGroupList this list is used to indicatie which position the article has in a article group. A product can be in multiple groups and have different positions in each one of these. Use the function getArticleGroups to get a full list of the article groups.

getArticleGroups Retrieving all article groups

Article groups are used to divide products into main and sub categories.

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<?php
 
require_once('Mplusqapiclient.php');
 
$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.
 
// Then we call the getArticleGroups() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($article_groups = $mplusqapiclient->getArticleGroups())) {
    // Success, we show the amount of found article groups
    exit(sprintf('Found %d article groups.', count($article_groups)));
  } else {
    exit('Failure while getting article groups.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

createProduct Creating a new article

When creating an article, you need to wrap your new article in a product. See above for an explanation of the difference between products and articles.

Currently, it is possible to use the following properties when creating a new product or updating an existing one:

  • article.articleNumber
  • article.pluNumber
  • article.description
  • article.invoiceText
  • article.receiptText
  • article.displayText
  • article.barcode
  • barcodeDate
  • article.turnoverGroup
  • article.vatCode
  • article.purchasePrice
  • article.priceIncl
  • article.priceExcl
  • article.colour
  • article.size
  • article.brandName
  • article.extraText
  • article.extArticleId
  • article.supplierRelationNumber
  • article.supplierArticleNumber
  • article.categoryId
  • article.siUnit
  • orderQuantity
  • discontinued
  • stockSiUnit
  • article.customFieldList

After you create a product, the result will contain the productNumber and articleNumbers of the new product and article(s).

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
<?php
 
require_once('Mplusqapiclient.php');
 
$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.
 
// First we create the array that will hold the new article's data, don't forget to wrap in a product.
$product = array(
  // 'productNumber' => 101, // productNumber is optional, if you don't add it, Mplus will choose a productNumber for you.
  'description' => 'Bike',
  'articleList' => array(
    array(
      // 'articleNumber' => 130, // articleNumber is optional, if you don't add it, Mplus will choose a articleNumber for you.
      'description' => 'Bike',
      'priceIncl' => 19900, // prices are always in cents
      'turnoverGroup' => 50,
      'vatCode' => 2,
      'customFieldList' => array(
        /*array(
          'fieldName' => 'test_field', // first, you need to add a custom field labeled "test_field" to your Mplus administration
          'strValue' => 'test',
          ),*/
        ),
    ),
  ),
);
 
// Then we call the createProduct() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($product_result = $mplusqapiclient->createProduct($product))) {
    // Success, we show the new product's and articles' internal identifier.
    exit(sprintf('Created new product with number %s and article number(s) %s.', $product_result['productNumber'], isset($product_result['articleNumbers'])?implode(', ',$product_result['articleNumbers']):'?'));
  } else {
    exit('Failure during product creation.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

updateProduct Updating an existing article

When updating an existing article, you also need to wrap the updated article data in a product. See above for an explanation of the difference between products and articles. Don’t forget to supply the productNumber and articleNumber so the API knows which product/article you mean.

Currently, it is possible to use the following properties when creating a new product or updating an existing one:

  • article.articleNumber
  • article.pluNumber
  • article.description
  • article.invoiceText
  • article.receiptText
  • article.displayText
  • article.barcode
  • barcodeDate
  • article.turnoverGroup
  • article.vatCode
  • article.purchasePrice
  • article.priceIncl
  • article.priceExcl
  • article.colour
  • article.size
  • article.brandName
  • article.extraText
  • article.extArticleId
  • article.supplierRelationNumber
  • article.supplierArticleNumber
  • article.categoryId
  • article.siUnit
  • orderQuantity
  • discontinued
  • stockSiUnit
  • article.customFieldList

After you update a product, the result will contain the productNumber and articleNumbers of the existing and new article(s).

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
<?php
 
require_once('Mplusqapiclient.php');
 
$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.
 
// First we create the array that will hold the new article's data, don't forget to wrap in a product.
$product = array(
  'productNumber' => 101, // Let's assume the product's number is 101
  'description' => 'Bike',
  'articleList' => array(
    array(
      'articleNumber' => 130, // Let's assume the article's number is 130
      'description' => 'Bike',
      'priceIncl' => 19900, // prices are always in cents
      'turnoverGroup' => 50,
      'vatCode' => 2,
    ),
  ),
);
 
// Then we call the updateProduct() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($product_result = $mplusqapiclient->updateProduct($product ))) {
    // Success, we show the existing product's and existing and new articles' internal identifier.
    exit(sprintf('Updated existing product with number %s and existing article number(s) %s and new article number(s) %s.', $product_result['productNumber'], isset($product_result['existingArticleNumbers'])?implode(', ',$product_result['existingArticleNumbers']):'?', isset($product_result['newArticleNumbers'])?implode(', ',$product_result['newArticleNumbers']):'?'));
  } else {
    exit('Failure during product updated.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

getPriceGroupList Retrieves the current list op pricegroups

When u retrieve products or a relation they can contain pricegroup information this function gets the list with numbers and names of all possible pricegroups.

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?php
require_once('Mplusqapiclient.php');
$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.
(...)
// Then we call the getPriceGroupList() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($pricegroups= $mplusqapiclient->getPriceGroupList())) {
    // Success, we show the number of retrieved pricegroups.
    exit(sprintf('Retrieved %d pricegroups.', count($pricegroups)));
  } else {
    exit('Unable to retrieve pricegroups.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

getSalesPriceList Retrieves the current list op salesprices

When u retrieve products they can contain salesprice information this function gets the list with numbers and names of all possible salesprices.

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?php
require_once('Mplusqapiclient.php');
$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.
(...)
// Then we call the getPriceGroupList() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($salesprices= $mplusqapiclient->getSalesPriceList())) {
    // Success, we show the number of retrieved salesprices.
    exit(sprintf('Retrieved %d salesprices.', count($salesprices));
  } else {
    exit('Unable to retrieve salesprices.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

getOverview

The getOverview call can be used with the cardType PRODUCT to retrieve a list of products this is an alternative to the getProduct call. This call can be used to paginate your products.

updateBatch

When used with the cardType PRODUCT it can update most product properties.

Best Practices
How to keep your application up to date with the latest data

The best way to keep your application up to date with our articles is through the use of the syncMarker property.

How you ask? When your application runs for the first time you call getProducts with a syncMarker of 1. This will return a list of articles from the API (for a maximum of 1000 at a time).

You then start processing the list and each time you do you save the highest syncMarker that was processed. For your next run you take the syncMarker that you saved, increment its value with 1 and use that for your next call to getProducts.

When articles are changed on our side, its syncMarker gets updated. Therefore, if you use this method, you will only receive a list of all the changed articles. This makes for a faster and more efficient synchronization process.

Learn more about Sync Markers here.