Ship Logic Courier Delivery Setup and Usage

To view instructions on creating a shipment from an Invoice without an overview of the relevant form components, click here. 

Set Up

Ship Logic Account

From the Account Settings page in Ship Logic, click the Create API Key.

Copy the API Key to the clipboard and store it somewhere safe.

API Setup

Return to Huge ERP and navigate to API Setup in the SCM module under Security. 

Click the Add button in the top toolbar. 

Select Ship Logic API from the API combo box in the Add form.

In the Location field enter "api.shiplogic.com" without the quotes.

In the User Name field enter the email address used to log into Ship Logic. 

Copy the API Key copied from the Ship Logic Account Settings page to the API Key field.

In the config field enter "bearer" without the quotes.

Make sure the Active checkbox is checked. 

Click Save when done.

Creating a Delivery Company

To select Ship Logic as the API for courier delivery for an Invoice or other applicable document, it first needs to be added as a Delivery Company in Creditors Setup in the Creditors Module under Configuration.

Click the Add button in the top toolbar.

In the Details tab fill in the Credit Code, Name and Short Name fields for the Delivery Company. Other information in this tab is optional.

Save the form by clicking the Save button, and then switch to the Info tab. 

In the Use Courier API combo box select Ship Logic API, then save the form again. The form can now be closed.

Shipping Terms

In addition to creating a Delivery Company for Ship Logic, Shipping Terms need to be created for selecting the Delivery Company from an Invoice form.

Navigate to Additional Debtor Properties in the Debtor module under Configuration. Switch to the Shipping Terms tab.

Click the Add button in the top toolbar.

In the Shipping Method form enter a Code and Description in the respective fields.  Select Delivery for the Ship Type combo box and External for the Delivery By combo box.

The Delivery Company combo box should be enabled after selecting External for the Delivery By combo box. Select the created Delivery Company for the combo box.

Make sure the Active checkbox is checked, and then click Save & Close. 

It should now be possible to create shipments with Ship Logic from Invoice forms.

Optional - Service Types

Optionally Service Types can be created to populate the Service Type combo box in the Shipping tab of the Invoice form. To do this navigate to Courier Setup in the SCM module under Administration.

Service Types can be added, edited and deleted from this panel. The selected API should be Ship Logic API and the Code should be unique for Ship Logic. The codes should correspond to valid Service Type codes for Ship Logic. Service Types available for a delivery can be viewed as described by clicking the Courier API or Get Rates button in the Shipping tab of the Invoice form, as described in the next section.

Optional - Predefined Parcel Sizes

Predefined parcel sizes can be created in the Courier Setup panel in the Parcel Sizes tab, or in the Defaults tab in the Parcel Selection grid, which is described in the next section. Predefined parcel sizes can be used as templates to create new parcel entries with the same values for a new shipment from the Parcel Selection for an Invoice. The selected API should be Ship Logic and the name should be unique. The dimensions and weight should all be provided.

Using Ship Logic to Create Shipments

Shipments can be created from the document types:

• Invoice

• Sales Order

• Sales Order Confirm

• Dispatch Stock Documents  

The process to create a shipment is identical for all document types, however the delivery status can only be updated automatically from Invoice documents at this point.

Outside of the document form, the Collection address is retrieved from the Company Profile Info form in SCM. Currently only the physical address fields are selected.

Address Fields

Field	Description	Example
Address Line 1	The street address	1188 Lois Avenue
Address Line 2	The suburb, or local area	Menlyn
Address Line 3	The city	Pretoria
Address Line 4	The region or province	Gauteng
Country	The selected country, defaults to South Africa	South Africa
GPS Coords	Optional GPS coordinates, comma separated latitude then longitude	-25.7863272, 28.334732

Creating Shipments from an Invoice

An Invoice to create a shipment from can be in Preparation or Posted Status. If in Posted status, only the fields in the Shipping tab can be edited.

At a minimum, outside of the Shipping tab fields, the Customer, Internal Contact and Contact Person fields are required.

Components and fields that may be used are marked red in the screenshots, and the fields that are not used are marked purple. Buttons that are optionally used are marked yellow.

Detail Tab components

Component	Used	Required	Description
Customer	Yes	Yes	Used for Delivery Address and Delivery Contact. Required to save a new Invoice. The delivery address used is the Customer address for the Address Type selected in the Shipping tab. The numbered address fields are required to be for the same address components as the Branch Address, e.g. Address Line 1 is for the Street Address. If a Contact Person is not selected from the Address tab then the Delivery Contact is obtained from the selected customer instead. The first name, last name, email and mobile number of is used, with the name and either the email or mobile number being required.
Sales Rep	No
Reference	Yes	No	Becomes the customer reference for the delivery if set
Internal Contact	Yes	Yes	Used for the Collection Address and Collection Contact. The collection address becomes the Physical Address of the Branch the user belongs to. The first and last name, and email and mobile number are used, with the email or mobile number being required as with the Delivery Contact.

Address Tab components

Component	Used	Required	Description
Address Type	No		Address that when selected will populate the address fields in this tab.
Address Fields	No		Currently is not used. Instead the unedited customer address for the selected customer in the Detail Tab and address type in the Shipping Tab is used for the delivery address.
Contact Person	Yes	No	Overrides the default contact person for the Customer if selected. The name and email or mobile number of the Contact Person is required.
View Button	N/A	No	Can be used to edit the details for the selected Contact Person.
Contact No	Yes	No	If set then this Contact Number is used instead of the Mobile Number for the selected Contact Person or default Debtor Contact Person.
Region	No		Is unrelated to the Region given in the addresses.
Branch	No		The branch address is from the branch the Internal Contact belongs to.

Shipping Tab components

All of the components in the main area, that are not marked purple in the screenshot are required or are used for Courier Delivery related functions with Ship Logic. The components that are required to create a Shipment are marked red.

Component	Used	Required	Description
Shipping Terms	Yes	Yes	Required to populate the Delivery Company combo box and then select the Courier Company for Ship Logic. For more information view the Set Up section.
Collect / Ship Date	No		Currently not used for Ship Logic, but could be used to schedule the collection date and time.
Shipping Options - email	Yes	No	If checked then delivery updates are sent to the Collection contact by email or SMS.
Shipping Options - other	No		These shipping options do not apply to Ship Logic. [NEW]
Pickup Instructions	Yes	No	Special instructions for the delivery driver when collecting the shipment. [NEW]
Delivery Instructions	Yes	No	Special instructions for the delivery driver when delivering the shipment. [NEW]
Delivery Company	Yes	Yes	Required to select the Courier Company that has for its Courier API field Ship Logic set. For more information view the Set Up section.
Address Type	Yes	No	The type of customer address such as Physical, Delivery or Postal. If unselected then the Delivery address is used.
Validate Button	No	No	Validating address is unsupported by Ship Logic. Click this button will show an error indicating this. [NEW]
Update Customer Address	No	No	Requires address validation to be supported. [NEW]
Parcel Dimensions display field	No	No	Displays the information about the current parcel selection for the shipment to be created. If blank then there is no parcel selection. If faded then the shipment was created for the parcel selection.
Custom Parcel Dimensions button	N/A	Yes	Clicking on this opens the Parcel Selection window, which is required for specifying information about the parcels for the shipment. This is explained in the next section.
Service Type	Yes	No	Is now used to pre-select a rate from the list of available rates retrieved from ShipLogic that are presented when the Courier API button is clicked.
Tracking No	No		Displays the last Tracking Number that is assigned to the Invoice. This can be edited and be related to shipping functions outside of ShipLogic.
Tracking No buttons	No		These buttons can be used to add a new Tracking Number to the Invoice or view the list of existing Tracking Numbers for the Invoice. The tracking numbers do not need to have been created with Ship Logic.
Delivery Status display field.	Yes	No	Displays the current shipping status for the last shipment created with Ship Logic.
Update Delivery Status	Yes	No	Clicking this button will perform an API request with Ship Logic to update the Delivery Status display field.
Auto checkbox	Yes	No	Having this checked will cause the Delivery Status display field to be updated when the Invoice is opened and there is a shipment created with Ship Logic for it.
Courier API button	Yes	Yes	This button is required to be clicked on before a shipment for the Invoice can be created with Ship Logic. If there is a selection of parcels created, and the other requirements are met, a window with a list of available shipping rates, or services types, will be presented, of which one can be selected and a shipment created. [NEW]
Details	No		For unrelated shipping functions. The Pickup and Delivery instructions may also be set in the form that opens after clicking the button, but it is unnecessary when these fields already exist in the current form.
Save Shipping	Yes	Yes	Is required to save the Shipping Tab fields if the Invoice Save button is disabled as it is when the Invoice status is Posted. The Customer, Internal Contact and Reference fields are not saved. The Shipping Tab fields are also saved automatically when the Courier API button is clicked.

Parcel Selection Grid

The Parcel Selection Grid is opened in a new modal window by clicking the Custom Parcel Dimensions button next to the Parcel Dimensions field. It is required to have at least one parcel created before a new shipment can be created with Ship Logic.

When there is one or more parcel for the new shipment, the Parcel Diminsions field in the Shipping tab of the Invoice form will be updated to reflect this. In this case the text is coloured black. If the parcel dimensions are greyed out, then the parcels the dimensions are for have been assigned to the last created shipment, and for to create a new shipment new parcel dimensions will need to be added [NEW].

Example of Parcel Dimensions created for the next shipment.

Example of Parcel Dimensions assigned to the last created shipment.

The Parcel Selection Grid is used for several purposes:

• As indicated before, to add and edit the required information about the parcel sizes for a new shipment

• Editing predefined parcel sizes to use instead of having to reenter the same values each time.

• Keeping a record of past shipments [NEW]

• Viewing and updating the tracking information for parcels that have been assigned to a shipment [NEW]

Editing Parcel Dimensions

For a shipment to be created with Ship Logic the dimensions and weight need to be specified. The quantity is optional and can be used instead of copying a parcel with the same dimensions and weight for the value of quantity.

Selection Grid

Component	Description
Search button	Clicking this will reload the grid from the server
Add	Clicking this opens a dialog to add a new parcel
Edit	When one row is selected and is for a parcel without a shipment, the same dialog that is opened with the Add button is opened to edit information for the selected row.
Delete	When at least one row is selected and the rows do not include rows for created shipments, the rows will be deleted without confirmation. Multiple rows are selected by holding down the control key and clicking on the rows to add to the selection.
Include Tracked [NEW]	To include parcels with a shipment in the grid this checkbox is checked. To only show the parcels for the next shipment, it is unchecked.
Name column	The name given to the parcel. This is not required by Ship Logic but is necessary if created from a parcel template.
Shipment column [NEW]	This column is hidden by default. To unhide it, open the menu for the column and check the box for it in the "Columns" submenu. If there is a shipment number associated with the parcel then it is shown in the row. If there is not shipment number but there is tracking number then "Unavailable" is shown To group the rows by this column, open the menu for the column and click "Group by this field".
Shipment Created [NEW]	This column is hidden by default and needs to be enabled in the Columns submenu. If a shipment was created that includes the parcel this column will show the date and time it was created if this information is available.
Dimensions (L x W x H)	Show the length, width and height of the parcel in centimeters
Wgt	The weight in kilograms
Qty	The number of parcels with the same dimensions and weight in the shipment
Close button	Closes the window. When the window is closed the Parcel Dimensions field in the Shipping tab of the Invoice form will be refreshed from the server.

 

Add / Edit dialog

Opened by clicking the Add or Edit buttons

The Parcel combo box can be used to select a parcel template created in the Defaults grid and prefill the remaining fields.

Defaults grid

Lists predefined parcel dimensions that can be selected and added to the Selection grid for the next shipment.

To select more than one row, hold down the Control key before clicking on the next row.

When one or more rows are selected the Add Selected button becomes enabled. Clicking on it will create new parcel dimensions, with the values of the selected rows, in the Selection grid for the next shipment. When the new rows are added successfully, the tab is automatically switched to the Selection grid.

Editing Predefined Parcel Dimensions

To add and edit predefined parcel dimensions click the add and edit button respectively. A row needs to be selected before it can be edited. Multiple rows can be deleted together by selecting more than one by holding the Control key, and then clicking the Delete button.

Add / Edit Dialog

Entering a name is required and if a Courier API is selected then it is required to be unique for the selected API. The name will appear in the combo box in the add/edit dialog for the parcel selection grid. The dimensions and weight are required fields for Ship Logic.

Viewing Past Shipments

In the parcel selection grid, created shipments can be viewed by checking the Include Tracking checkbox. If a shipment was created with Ship Logic then the parcels for it should have the Shipment number assigned to it, the Shipment Created column will have the date and time the shipment was created and there should be a distinct tracking number for each parcel in the Tracking Number column. A column for the Tracking URL of each parcel in the shipment is also available.

If a parcel has a quantity greater than one, then in the Tracking Number and Tracking URL columns there will be a new line for each of the parcels that make up the quantity.

These columns are hidden by default and will need to be unhidden.

Rows can be grouped by the Shipment number, but changing the sort order of groups is currently unsupported and the groups are always sorted in ascending order. To isolate to a single shipment, one can be selected from the Shipment combo box in the search panel. Available shipments are sorted by the time and date they were created in descending order.

Updating Tracking Information

To update the Delivery Status for the parcels belonging to a shipment, select a row for a parcel with a Shipment number, then click the Status button in the top toolbar of the window. If successful then the columns API Status, API Parcel Status and Status Updated will be updated. The API Status column in the Delivery Status for the shipment, whereas the API Parcel Status is the delivery status of the parcel. The Status Updated column is the date and time the delivery status was last successfully updated.

If a parcel has a quantity greater than one, then in the API Parcel Status column there will be a new line for each of the parcelsthat make up the quantity.

Creating a Shipment

Invoice Set up

A shipment is created Ship Logic from an Invoice by clicking on the Get Rates or Courier API button in the Shipping Tab when the required information has been saved to the Invoice and is correct.

Required Steps

To create a Shipment with Ship Logic from an Invoice document the following is required before clicking on the Get Rates or Courier API button in the Shipping Tab:

• The Invoice needs to have a Customer selected

• The address selected in the Address Type field needs to be valid for the Customer.

• An Internal Contact needs to be selected

• The Physical Address for the Branch the Internal Contact belongs to needs to be valid

• For an address to be valid it needs to be in the following format:

  Field	Description	Example
  Address Line 1	The street address	1188 Lois Avenue
  Address Line 2	The suburb, or local area	Menlyn
  Address Line 3	The city	Pretoria
  Address Line 4	The region or province	Gauteng
  Country	The selected country, defaults to South Africa	South Africa
  GPS Coords	Optional GPS coordinates, comma separated latitude then longitude	-25.7863272, 28.334732

• The Customer needs to have a default contact person, or the Contact Person in the Address tab needs to be given.

• The contact person needs to have a name and a valid contact number or email

• If the Contact Number field in the Address tab is used, then this replaces the Contact Number for the Contact Person

• The Internal Contact needs have a name and a valid contact number or email.

• From the Parcel Selection grid accessed from the Shipping Tab, there needs to be at least one parcel created, with dimensions and a weight, and that has not been assigned a Shipping number or Tracking number.

• The API needs to be set up correctly

• In the Shipping Tab the Shipping Terms that apply to Ship Logic needs to be selected

• In the Shipping Tab the Delivery Company for Ship Logic needs to be selected

• The Invoice needs to be saved. Unsaved information is not sent to Ship Logic. If it is a processed Invoice then clicking the Save Shipping button in the Shipping Tab can be used, however the Customer and fields outside of the Shipping Tab will not be saved.

Optional Steps

• If the Email checkbox is checked in Shipping Options in the Shipping Tab, then delivery updates are sent to the Internal Contact via email or SMS.

• Special instructions for collection and delivery can be set from the Shipping Tab in the Pickup and Delivery Instructions fields.

• If the Reference field in the Detail Tab is set then this becomes the Customer Reference

• Selecting a Service Type from the Shipping Tab will preselect it when the Rates Selection List is presented, if it is available. Otherwise, if Economy is available then it will be selected.

Selecting from the Available Rates

When the Invoice is ready clicking the Get Rates or Courier API button in the Shipping Tab will present a new window with a list of the available rates or Service Types and their associated costs and other relevant information. By default the Economy rate, if it is available will be preselected, but if the Service Type selected from the Shipping Tab is available it will be preselected instead. Another rate can be selected by clicking on it. When a rate is selected the Select button in thet bottom toolbar will be enabled.

Clicking the Select button will create a shipment with Ship Logic with the selected option.

Clicking the Cancel button will close the window without creating a shipment.

If the Select button was clicked and a Shipment was created successfully with Ship Logic, then a success message with the tracking number will appear.

The tracking number will also be added to the Invoice in the Tracking No field and to the Tracking Number list opened by clicking the View Tracking Numbers button next to it.

When the success message is dismissed, the Waybills or parcel labels will be automatically downloaded by the browser as a PDF file. The shipping documents, which include the labels, will be saved as attachments to the Invoice.

The Parcel Dimensions field in the Shipping Tab will be greyed out to indicate that the parcels it references are assigned to a shipment.

In the Parcel Selection window the Shipment combo box will show the Shipment number for the created shipment with the date and time it was created.

The rows for the parcels belonging to the Shipment are updated as follows:

• The ID or number given to the Shipment by the Ship Logic will set in the Shipment column

• The Shipment Created column will be updated with date and time the Shipment was created

• The Status column will be updated to "In Transit"

• The API Status column is updapted with a description of the delivery status for the Shipment from the API

• The Tracking Numbers and Tracking URLs for each of the parcels will be set

Attachments

The attachments created by Ship Logic can be viewed with other attachments for Invoice, in the Attachments window, opened by clicking the Attachments button in the top toolbar of the window for the Invoice.

The attachments added for the created shipment will include "ShipLogic" and the tracking number in their names.

Delivery Status Updates

The Delivery Status for the last created shipment belonging to the Invoice can be updapted by clicking the Update Delivery Status button next to the Delivery Status field in the Shipping Tab. To automatically update the delivery status when any Invoice is opened the Auto checkbox next to the button can be checked.