API Documentation
      Back to home
      1. Knowledge Base
      2. Modules & Features
      3. API Documentation

      How to Use Customers, Bill-To Address, and Ship-To Address with Orders in the Infoplus API

      See the rules and use cases for how the customerNo and billTo, and shipTo address fields function for Orders in Infoplus when used with an API

      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: 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).  


      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.

       

      Rules Around Address Fields

      The billTo and shipTo addresses each have the following fields, with the following rules:

      Bill to field name Ship to field name Usage Details
      billToCompany shipToCompany Required. (Unless using the billToAttention and shipToAttention fields) Used as the first line of the full address (whether the address is for a business or an individual)
      billToAttention shipToAttention Required. (Unless using the billToCompany  and shipToCompany field)  If given, it is used as a second line of the full address, above the street lines.  
      billToStreet shipToStreet Required.  
      billToStreet2 shipToStreet2 Optional.
      billToStreet3 shipToStreet3 Optional.  Suggested to use for province or region name for non-U.S. addresses.  
      billToCity shipToCity Required. 
      billToState shipToState Required for U.S. addresses.  Not allowed for non-U.S. addresses.  The province or region for non-U.S. addresses can be put in Street3.  
      billToZip shipToZip Required for U.S. addresses.  Optional for non-U.S. addresses.  
      billToCountry shipToCountry Required for non-U.S. addresses.  Optional for U.S. addresses.  
      Note: For US orders, you must use "USA" or leave this field blank and just specify the State and City. The system does not recognize any value other than "USA" for US orders. If the country field is left blank, the billTo address will be used instead. For non US orders, the country must be spelled out and not abbreviated as well. 

       

      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:

       

       

      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:

       

       

      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:

       

      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).