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

      How to get Shipments with the Infoplus API

      There are multiple approaches you can take to identify when an Order in Infoplus has been shipped, here's a few options to perform this action.

      Many users of the Infoplus API need to query Infoplus to get Shipment information about their Orders.  In Infoplus, information about your Shipments can be found by looking in two tables:


      In the Order table, Infoplus records values in the following fields when an order is shipped:

      • shipDate - date that the order was marked as shipped in Infoplus.  Note that this date can potentially be either in the future, for orders that are staged for future shipment, or in the past, for orders which have their parcel labels produced on one day, but which are not actually marked as shipped until a later date.  
      • freightAmount - total dollar amount spent on parcel labels for shipping the order
      • weightLbs - total weight for the order recorded as it was shipped
      • cartonsShipped - total number of cartons shipped
      • status - the status of an order becomes Shipped when the order is shipped.
      Parcel Shipments
      • trackingNo - the package tracking number assigned by the carrier
      • weightLbs - weight of the package
      • publishedFreightAmount - dollar amount that would be charged for the shipment assuming no contracted discounts were applied to the shipment (Note, may not be available for some carriers and/or service levels)
      • chargedFreightAmount - dollar amount charged for the shipment based on the negotiated/contract rate for the shipment on the account with which it was shipped (Note, may not be available for some carriers and/or service levels, or for 3PL users of Infoplus)
      • retailFreightAmount - dollar amount that would be charged for the shipment if it were bought at a retail rate (Note, may not be available for some carriers and/or service levels)

      Finding Shipped Orders

      There are multiple approaches you can take to identify when an Order in Infoplus has been shipped.  Which one you choose may depend on what capabilities you have in the system you are integrating with Infoplus.  Below are some options you can use.  


      Note that for each of these search queries, by default, a max of 20 records will be returned.  This page size can be controlled by using the limit query-string parameter, with a max allowed value of 250.  Whatever page size you use for your query, if you get back as many rows as your input page size (limit) was, then you should make subsequent requests to fetch additional pages of data, using the page parameter.  The default value for page is 1 (as page is a 1-based index -- not 0-based).  If you specify a page value that takes you past the end of your result set, you will get back an empty list - this can serve as the signal to stop requesting more pages.  


      1 - Search by orderNo

      If you know a list of specific orders that you want to check on the shipping status for, you can construct a search query that lists those orderNo values, and include a clause to only include the ones that are Shipped.  This may work well if you are tracking the orders in a database outside of Infoplus, and marking the orders as being shipped in that system, once you see that they are shipped in Infoplus.  Here's an example of a filter that can be used on a GET request to the Infoplus API's order/search endpoint (or passed in to the orderAPI object's search method, if you are using a client library), to search for a list of orderNo's that are in the Shipped status:   

      orderNo in(119,120) and status eq Shipped


      2 - Search by order modifyDate 

      Alternatively, you may not have a list of orderNo's available, so you may just wish to search for orders that have been updated since some point of time (either a fixed window of time (i.e., always 1 hour or 1 day) or based on the last time you searched for updates).  In this case, you can search orders using the modifyDate field, where it is greater than (gt) the timestamp you supply:

      modifyDate gt '2020-12-31T12:59:59.999Z' and status eq Shipped

      3 - Search using custom field (after API version 1.0)

      As a third option, you may add a custom field in Infoplus to your orders table, where you can track within Infoplus whether or not you have pulled the shipment information for individual orders into your system.  In this case, you could query for where the custom field does not have a value, then for each order received, update the custom field, to prevent further searches from finding the same order.  You may need to speak with the Infoplus support team for more information on using a custom field for this purpose.   

      custom.hasShipmentBeenPulled is blank and status eq Shipped


      Then, for each order you get from that search, issue a PUT to the customFields endpoint to set the value in the custom field that will prevent the order from being found on subsequent calls:  

      {
         "orderNo": ${orderNo}
         "customFields": 
         {
            "hasShipmentBeenPulled": true
         }
      }


      Getting parcel shipments for shipped orders

      After you have identified an order which is shipped, to get information on the parcel shipments under that order, you'll need to do a search of the parcelShipment table for the orderNo you're looking for.  This is as easy as using the filter shown below (again, considering the default limit of 20 rows per page, you may wish to use a higher value for the limit parameter, and given that few orders are likely to ship with more than 250 parcels, it is unlikely that pagination on this search would be needed).

      orderNo eq 1234