Orders

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

Introduction

Using these API functions, you can interact with the MplusKASSA order workflow.
Whenever you create an order externally, you have to supply an external order identifier (extOrderId). You can use this identifier to find the order again.
External order identifiers are unique and therefore cannot be reused.

Notice: Orders are different from table orders, an order can not be changes to a tabel order. Make sure you implement the correct one for your use case.

Contents

getOrders Retrieving orders

When you want to synchronize orders from Mplus to another application, it is smart to make use of Sync Markers.

<?php

require_once('Mplusqapiclient.php');

$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.

$syncMarker = get_internal_orders_syncmarker(); // this should be 0 the first time you synchronize

// Then we call the getOrders() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($orders = $mplusqapiclient->getOrders($syncMarker))) {
    // Success, we show the number of retrieved orders.
    exit(sprintf('Retrieved %d orders.', count($orders)));
  } else {
    exit('Unable to retrieve orders.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

createOrder Creating a new order

When creating an order, you are always required to attach a relation.
See the relations tutorial to learn how to manage relations through the API.

<?php

require_once('Mplusqapiclient.php');

$mplusqapiclient = new Mplusqapiclient(); // Initialize the client with your details. 

// First we create the array that will hold the new order's data. 
$order = array(
  'extOrderId' => 'ORDER0001359', // any string is allowed, but must be unique
  'entryBranchNumber' => 1, // branchNumber must be present in Mplus
  'relationNumber' => 681, // relationNumber must be present in Mplus
  'employeeNumber' => 999999, // employeeNumber must be present in Mplus
  'reference' => 'Bestelling #1359', // an extra optional reference text
  'orderCategoryNumber' => 0, // retrieve the available orderCategories through getOrderCategories
  'deliveryMethod' => 'OPHALEN', // retrieve the available deliveryMethods through getDeliveryMethods
  'deliveryAddress' => array(
    'name' => 'Mplus Software',
    'contact' => 'Jan de Boer',
    'address' => 'Voorstreek 77',
    'zipcode' => '8911JL',
    'city' => 'Leeuwarden',
    'country' => 'Nederland',
  ),
  'invoiceAddress' => array(
    'name' => 'Mplus Software',
    'contact' => 'Jan de Boer',
    'address' => 'Voorstreek 88',
    'zipcode' => '8911JL',
    'city' => 'Leeuwarden',
    'country' => 'Nederland',
  ),
  // options are:
  // (1) VAT-METHOD-INCLUSIVE (VAT included)
  // (2) VAT-METHOD-EXCLUSIVE (VAT excluded)
  // (3) VAT-METHOD-SHIFTED (VAT shifted, for international business)
  'vatMethod' => 'VAT-METHOD-EXCLUSIVE',
  'lineList' => array(
    array(
      'articleNumber' => 14, // articleNumber must be present in Mplus
      'data' => array(
        'quantity' => 1,
        'price' => 1995, // prices are always in cents
        'discountPercentage' => 15, // optional discountPercentage
        'discountAmount' => 0, // optional discountAmount
        'vatCode' => 2, // VAT code
      ),
      'text' => 'Stropdas',
    ),
    array(
      'articleNumber' => 999, // articleNumber must be present in Mplus
      'data' => array(
      'quantity' => 1,
      'price' => 495, // prices are always in cents
      'discountPercentage' => 0, // optional discountPercentage
      'discountAmount' => 0, // optional discountAmount
      'vatCode' => 2, // VAT code
    ),
    'text' => 'Shipping costs',
  ),
  array(
    'text' => 'tekstregel',
  ),
);

// Then we call the createOrder() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($order_result = $mplusqapiclient->createOrder($order))) {
    // Success, we show the new order's internal identifier.
    exit(sprintf('Created new order with id %s.', $order_result['orderId']));
  } else {
    exit('Failure during order creation.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

Getting an existing order

There are two ways of retrieving an existing order. The first method is by searching for the external order identifier. The second method is by accessing the order with its internal order identifier.

findOrder Method one: Searching for external order identifier

<?php

require_once('Mplusqapiclient.php');

$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.

// Then we call the findOrder() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($order_result = $mplusqapiclient->findOrder('ORDER0001359'))) {
    // Success, we show the order's internal identifier.
    exit(sprintf('Found existing order with id %s.', $order_result['orderId']));
  } else {
    exit('Unable to find order.');
  }F
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

getOrder Method two: Getting order by its internal order identifier

<?php

require_once('Mplusqapiclient.php');

$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.

// Then we call the getOrder() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($order_result = $mplusqapiclient->getOrder('001a3cd43892405b9689134b36656063'))) {
    // Success, we show the order's internal identifier.
    exit(sprintf('Found existing order with id %s.', $order_result['orderId']));
  } else {
    exit('Unable to find order.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

updateOrder Updating an existing order

Updating an existing order is very similar to creating a new order, except this time you also add the internal order identifier.
That means you must first get the internal order identifier, for example by storing it when you first created the order, or by looking for it using the findOrder() function.

<?php
  
require_once('Mplusqapiclient.php');

$mplusqapiclient = new Mplusqapiclient(); // Initialize the client with your details.
// First we retrieve the current order details.
if (false === ($order = $this->getOrder('001a3cd43892405b9689134b36656063'))) { // You can also use findOrder and extOrderId
  exit('Order does not exist.');
}

// Then we modify the order array with the updated data. In this case, we change the lineList to:
$order['lineList'] => array(
    array(
      'articleNumber' => 14, // articleNumber must be present in Mplus
      'data' => array(
        'quantity' => 1,
        'price' => 1995, // prices are always in cents
        'discountPercentage' => 15, // optional discountPercentage
        'discountAmount' => 0, // optional discountAmount
        'vatCode' => 2, // VAT code
      ),
      'text' => 'Stropdas',
    ),
    array(
      'articleNumber' => 16, // articleNumber must be present in Mplus
      'data' => array(
        'quantity' => 2,
        'price' => 799, // prices are always in cents
        'discountPercentage' => 0, // optional discountPercentage
        'discountAmount' => 0, // optional discountAmount
        'vatCode' => 2, // VAT code
      ),
      'text' => 'Sokken',
    ),
  );

// Then we call the updateOrder() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== $mplusqapiclient->updateOrder($order)) {
    // Success
    exit('Order successfully updated.');
  } else {
    exit('Unable to update order.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

cancelOrder Cancelling an order

<?php

require_once('Mplusqapiclient.php');

$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.

// Then we initialize some variables
$orderId = '001a3cd43892405b9689134b36656063'; // This is the order we're cancelling

// Then we call the cancelOrder() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== $mplusqapiclient->cancelOrder($orderId)) {
    exit('Order successfully cancelled.');
  } else {
    exit('Unable to cancel order.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

payOrder Paying an order

You can use the prepay parameter to signal if the order has been shipped already (false) or has not (true). If prepay is set to true, you will only make a deposit payment to the order, if prepay is set to false, you will also create a packing slip (signifying delivery) and invoice.

<?php

require_once('Mplusqapiclient.php');

$mplusqapiclient = new Mplusqapiclient(); // Initialize the client with your details.

// Then we initialize some variables
$orderId = '001a3cd43892405b9689134b36656063'; // This is the order we're making a payment on $prepay = true; // True means we are making a deposit to this order, False means we are creating an invoice. 
$payments = array(
  array(
    'method' => 'K_WEBSHOP', // Must be defined in the Mplus database
    'amount' => 1995, // Equivalent to 19,95
  ),
);

// Then we call the payOrder() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== $mplusqapiclient->payOrder($orderId, $prepay, $payments)) {
    exit('Order successfully paid.');
  } else {
    exit('Unable to pay order.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

Voor het gebruik van deze call dienen er financiële afspraken gemaakt te worden met MplusKASSA.

deliverOrder Delivering an order

Successfully delivering an order creates a packing slip for that order, which can later be invoiced. You can use this to signal that an order has been shipped, but not yet paid.

<?php

require_once('Mplusqapiclient.php');

$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.

// Then we initialize some variables
$orderId = '001a3cd43892405b9689134b36656063'; // This is the order we're making a payment on

// Then we call the deliverOrder() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== $mplusqapiclient->deliverOrder($orderId)) {
    exit('Order successfully delivered.');
  } else {
    exit('Unable to deliver order.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

getDeliveryMethods Get a list of available delivery methods

<?php

require_once('Mplusqapiclient.php');

$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.

// Then we call the getDeliveryMethods() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($deliveryMethods = $mplusqapiclient->getDeliveryMethods())) {
    exit(sprintf('%d delivery methods found.', count($deliveryMethods)));
  } else {
    exit('Unable to retrieve delivery methods.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

getOrderCategories Get a list of available order categories

<?php

require_once('Mplusqapiclient.php');

$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.

// Then we call the getOrderCategories() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($orderCategories = $mplusqapiclient->getOrderCategories())) {
    exit(sprintf('%d order categories found.', count($orderCategories)));
  } else {
    exit('Unable to retrieve order categories.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}