Orders in Infoplus are directly associated with a single Customer record (the customerNo field on the Order object).  This Customer's data serves as the billTo address on the Order.  


Orders may also have an alternate shipTo address associated with them as well.  If they do, this data serves as the shipTo address for the order.  Note that an alternate shipTo address is data that is only stored at the Order level in Infoplus (i.e., it is not associated with a Customer record).  If an Order in Infoplus does not have an alternate shipTo address, then its effective shipTo address is the same as its billTo address (i.e., the address of the Customer associated with the Order).  


API Rules for customerNo and billTo Address Fields

Here are the rules for how the customerNo and billTo address fields function for Orders in Infoplus, specifically as exposed through the JSON API:


If customerNo is given and the Customer is found in the database:

   The specified Customer's address will be used as the billTo address on the Order.

   The billTo address fields, if given, will be ignored*


Else, If the customerNo is given, but the Customer is NOT found in the database:

   If the billTo address fields are given:

      A new Customer will be built, using the billTo address fields.

   Else, If the billTo address fields are NOT given:

      An error will be returned.


Else, If customerNo is NOT given:

   If the billTo address fields are given:

      A new Customer will be built, using the billTo address fields, and a unique customerNo.

   Else, if the billTo address fields are NOT given:

      An error will be returned.


Use Cases

The following Use Cases can be expressed to manage Customers and Orders through the Infoplus API:


Explicit Customer Management

Customers can be explicitly managed via GET/POST/PUT calls prior to placing Orders.  In this case, only customerNo would be passed when creating an Order.  

  • This use case gives API users the most control over their Customer records, and allows their data to be updated if it may have changed since a previous Order was placed.  
  • To use Explicit Customer Management, the calling system must have its own id's for customers.  These id's are given to Infoplus in the customerNo field (on both the Customer and Order objects).
  • As a tradeoff to the greater control offered by this use case, the cost is additional API calls necessary to manage Customers before creating an Order. 

Here's an example of how an implementation of Explicit Customer Management could be structured, using our PHP client library:

$infoplusCustomer = null;
$customerExisted = false;

try
{
   // Look for Customer 
   $infoplusCustomer = $customerApi->getCustomerByCustomerNo($lobId, $customerNo);
      $customerExisted = true;
 }
catch(Exception $e)
{
   // Customer didn't exist - they'll need to be inserted -- 
   // instantiate a Customer object and set key values in it
   $infoplusCustomer = new \Infoplus\Model\Customer();
   $infoplusCustomer->setLobId($lobId);
   $infoplusCustomer->setCustomerNo($customerNo);
}

// update address fields in customer (for either insert or update use case)
$infoplusCustomer->setStreet($customerStreet);
// ... etc

if($customerExisted)
{
   $customerApi->updateCustomer($infoplusCustomer);
}
else
{
   $customerApi->addCustomer($infoplusCustomer);
}

// Only set customerNo in order's data
$infoplusOrder->setCustomerNo($customerNo);
$orderApi->addOrder($infoplusOrder);


Implicit Customer Management

Customers can be lazily initialized in Infoplus, but still be uniquely tracked (i.e., associated with a customerNo maintained by the calling system) by always POST'ing customerNo and all billTo address fields when creating Orders.  In this case, if the Customer identified by the customerNo already exists in Infoplus, it will be used with its existing data as the Order's billTo address - otherwise (if the customer didn't exist in Infoplus), a new Customer record will be created, using the supplied customerNo and the billTo address from the Order as the new Customer's billTo address.  

  • This use case allows an API user to have their customerNo's associated with Customer and Order records in Infoplus.  
  • This use case also requires the calling system to have its own id's for customers.  These id's are given to Infoplus in the customerNo field (on both the Customer and Order objects).
  • A benefit to this approach is its simplicity.  Only a single API call is necessary to create an Order and to (if needed) create new Customers at the same time.  
  • A limitation of this approach is that a Customer who's address has been updated since they were originally created in Infoplus will not be updated, and the billTo address on their new Order will reflect their old address.


Here's an example implementation using Implicit Customer Management through our PHP client library:

$infoplusOrder = new \Infoplus\Model\Order();

// set both customerNo and billTo fields in Order.
// Customer will be created if not found, otherwise, re-used.
$infoplusOrder->setCustomerNo($customerNo);
$infoplusOrder->setBillToCompany($customerCompany);
$infoplusOrder->setBillToStreet($customerStreet);
$infoplusOrder->setBillToCity($customerCity);
$infoplusOrder->setBillToState($customerState);
$infoplusOrder->setBillToZip($customerZip);

// ... set additional fields in Order

$orderApi->addOrder($infoplusOrder);


No Customer Management

Customers in Infoplus can essentially be ignored by always passing all billTo address fields when creating an Order, and never passing a customerNo.  This will cause Infoplus to generate a unique Customer record for each Order.

  • This approach is simple, in that it only requires a single API call to create an Order.
  • This is the only realistic approach available for callers who do not have customer ids managed in a system outside of Infoplus.  
  • The downside to this approach is that one loses the ability to do any tracking of Orders by Customers or customerNo's in Infoplus.  


Here's an example of using No Customer Management through our PHP client library:

$infoplusOrder = new \Infoplus\Model\Order();

// only set billTo fields in Customer.
// A new Customer will be always be created with the billTo fields as their data.
$infoplusOrder->setBillToCompany($customerCompany);
$infoplusOrder->setBillToStreet($customerStreet);
$infoplusOrder->setBillToCity($customerCity);
$infoplusOrder->setBillToState($customerState);
$infoplusOrder->setBillToZip($customerZip);

// ... set additional fields in Order

$orderApi->addOrder($infoplusOrder);


Alternate Ship To Address

In all cases, if shipTo address fields are given, they are used as the alternate shipTo address for the Order.  Otherwise, if the shipTo address fields are not given, the billTo address (i.e., the Customer's address) is used as the Order's shipTo address. 


* Re: the billTo fields being ignored for Orders with existing Customers:  We are scoping out a future enhancement where we'll use the billTo data given with an order as an override billTo address on the Order (a concept which does not yet exist today in Infoplus.  Currently in Infoplus, the billTo data on an Order is the Customer's data).