GoSweetSpot 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

GoSweetSpot Account

Get the API Key

From the GoSweetSpot account navigate to the Preference & Settings page by selecting from the Administration menu. 

Scroll down and click Advanced Settings to expand this section.

Scroll to the bottom of this section and copy the API Access Token to the clipboard.

Get the Site ID 

The Site ID is linked to the collection address that is used when creating an account with GoSweetSpot.

From the GoSweetAccount navigate to the Users & Permissions page by selecting Manage Users from the Administration menu.

Copy the Site ID from the Site column that is linked to the collection address for courier shipments created from HugeERP.

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 GoSweetSpot from the API combo box in the Add form.

Copy the API Key from GoSweetSpot to the API Key field.

Make sure the Active checkbox is checked. 

The User Name and Password fields are not required and can be left blank.

The config field can specify optional settings. Each setting is required to be on a separated line and begins with the name of the setting followed by an equals sign and then the value for the setting. So far the available settings are as follows:

Name	Description
side_id	The Site ID to use if it is missing from the Company Branch setup
excludeContactInfo	If the value is "yes" without the quotes, then contact info for the delivery recepient, such as the name and phone number, is to be excluded when creating a shipment.

Click Save when done.

Adding the Site ID to the Branch 

Navigate to Copy Profiles in SCM under Administration, and open the form for the company branch in which GoSweetSpot is to be used.

Switch to the Address tab, and copy the Site ID copied from GoSweetSpot into the GoSweetSpot Site field, then save and close the form.

Creating a Delivery Company

To select GoSweetSpot as the API for courier delivery from an Invoice form or other document form, it first needs to be added as a Delivery Company in Creditors Setup.

Navigate to 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 GoSweetSpot then save the form again. The form can now be closed.

Adding Shipping Terms

Shipping Terms need to be created for selecting the Delivery Company from an Invoice or other document 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.

The opened window may contain the title Shipping Methods but it is for creating and editing a Shipping Terms instance [TBC fix language tag].

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. 

If the Default checkbox is checked, then when an Invoice or other document is first loaded the Shipping Terms from this form will be selected automatically. 

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

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 as 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 GoSweetSpot and the name should be unique. The dimensions and weight should all be provided. 

If there are no predefined parcel sizes created then when adding parcel sizes for a courier delivery from an Invoice form or other document form, the dimensions and weight values will need to be manually specified.

If the Name matches a pre-loaded stock size for GoSweetSpot, for instance "GSS-A1 SATCHEL" then the other fields will be ignored by GoSweetSpot and the rates for the delivery will be based on the stock size given by the name. The names have to match exactly. For more information see GSS Satchel Specific Rates – Help Centre (gosweetspot.com)

Using GoSweetSpot 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 the Invoice form at this point.

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 in addition to the delivery address given in the address fields in the Address tab of the form. 

Fields and other UI elements that are used for creating shipments with GoSweetSpot are marked red in the screenshots. Purple indicates that the field is not used.

Detail Tab

Component	Used	Required	Description
Customer	Yes	Yes	Required to save the Invoice. The address fields in the Address tab is populated with the address of the selected Customer. [TODO] The default contact is used as the delivery contact if the contact person is not set in the Address tab. [TBC - check if the contact information from the Debtor Details form is still in use]
Reference	No
Order Number	Yes	No	Used as the reference for the shipment.
Internal Contact	Yes	Yes	Used to get the Site ID from the Company Branch that the selected user belongs to.

Address Tab

Component	Used	Required	Description
Address Type	Yes		Address that when selected will populate the address fields in this tab for editing.
Address Lines 1-4	Yes		Line 1 is either a street address or building number. If it begins with a number then it is assumed to be a street address, otherwise the street address in contained in Line 2.    The lines following the street address line are for the suburb and city that order.    The address can be validated and corrected from the Shipping tab by clicking the Validate Address button.
Address Code	Yes		The post code for the address.
Contact Person	Yes	Yes	References the contact person for the delivery. The name, email and mobile or phone number of the contact person is included when the shipment is created, unless disabled in the API setup in the config field with the excludeContactInfo setting.     [TODO] 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	Yes	No	Can be used to edit the details for the selected Contact Person.
Contact No	Yes	No	[TODO] If set then this Contact Number is used instead of the Mobile Number for the selected Contact Person or default Debtor Contact Person.
Branch	No		The branch address is from the branch the selected Internal Contact belongs to.

Shipping Tab

Components Used

Components inside the main panel of the Shipping tab which are not used currently or are redundant in creating shipments or for other API functions with GoSweetSpot are highlighted purple in the next screenshot.

Component	Used	Required	Description
Shipping Terms	Yes	Yes	Required to populate the Delivery Company combo box and then select the Courier Company for GoSweetSpot. For more information view the Set Up section.
Collect / Ship Date	No		Currently not used by GoSweetSpot
Shipping Options - Email	Yes	No	If checked then delivery updates are emailed to the delivery contact.
Shipping Options - Signature	Yes	No	If checked then a signature is required on delivery.
Shipping Options - Saturday			If checked then delivery will be on a Saturday, increasing the rates.
Pickup Instructions	No	No	Not used with GoSweetSpot when using the Site ID.
Delivery Instructions	Yes	No	Special instructions for the delivery driver when delivering the shipment.
Delivery Company	Yes	Yes	Required to select the Courier Company that has GoSweetSpot set as its Courier API. For more information view the Set Up section.
Validate Button	No	No	Clicking this button will validate the address set in the Address tab and open a window with the result and options to update the address. For more information view the Validating the Delivery Address section.
Update Customer Address	Yes	No	Opens a window to edit the Customer address selected in the Address tab. When saved the address will be saved to the customer. [TBC - save to the document too]
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	No	No	Is no longer necessary for creating shipments.
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 the Courier API.
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 GoSweetSpot.
Delivery Status display field.	Yes	No	Displays the current shipping status for the last shipment created.
Update Delivery Status	Yes	No	Clicking this button will perform an API request 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.
Courier API button	Yes	Yes	This button is required to be clicked on before a shipment for the Invoice can be created with GoSweetSpot. 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 to create a shipment.
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.

Validating the Delivery Address

To validate and to correct the address that is entered into the address fields in the Address tab, click the Validate button  in the Shipping tab. The address that is validated is the address as it is in the fields, not the saved address. After the address is validated by GoSweetSpot a window will open with named address fields and the validation result in the Log field. If a field has been corrected by GoSweetSpot then an asterisk will appear next to it. 

After editing the address, validation can be performed again by clicking the Validate button  next to the Postcode field.  

Clicking the Close button will close the window, without making any changes. 

Clicking the Apply button  will copy the address fields as they are to the address fields in the Address tab of the Invoice form.

Clicking the Inv Only or Doc Only button will also save the address as the address type selected in the Address tab, to the document.

Clicking the "Inv & Cus" or "Doc & Cus" button  will copy the address to the form, save it, and save the address to the customer selected in the Detail tab as the address type selected in the Address tab.

Parcel Selection Grid

The Parcel Selection Grid is opened in a new 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 GoSweetSpot.

When there is one or more parcel for the new shipment, the Parcel Dimensions 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 for it have been assigned to the last created shipment. To create a new shipment, new parcel dimensions will need to be added.

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:

• 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

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

Editing Parcel Dimensions

For a shipment to be created with GoSweetSpot the dimensions and weight need to be specified or the name needs to match with a name of the a pre-loaded stock size from GoSweetSpot. The quantity greateer than one is optional and can be used instead of copying a parcel repeatedly.

Selection Grid

Component	Description
Search button	Clicking this will reload the grid from the server with the search results.
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	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. If the name matches a pre-loaded stock size from GoSweetSpot, then this stock size is used by GoSweetSpot when creating a shipment.
Shipment column	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. For a parcels that are new it will show "Not Created". If there is a shipment number for the parcel then it is shown. 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	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 shows the date and time it was created.
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 identical parcels 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 from the selected rows in the Selection grid that are to be included in 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 or edit predefined parcel dimensions click the add or edit buttons. 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 by GoSweetSpot if the name does not match with the name of a pre-loaded stock size. 

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 the parcel then the Shipment, Shipment Created, Tracking Number and Tracking Number columns will contain values for shipment.

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

Rows can be grouped by their Shipment numbers or Shipment Created dates, but while grouped are not able to be sorted in descending order [TBD - find out if this can be fixed]. To only show the parcels for a single shipment, one can be selected from the Shipment combo box in the search panel. Available shipments in the drop down list are sorted by the time and date they were created in descending order.

Updating Tracking Information

To update the Delivery Status for all 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 is the Delivery Status for the shipment, whereas the API Parcel Status is the delivery status of the consignment the parcel is part of, if the shipment was split into multiple consignments. 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 parcels that make up the quantity.

Creating a Shipment

Invoice Set up

A shipment is created with GoSweetSpot from an Invoice by first 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, and then when the GoSweetSpot Delivery Options window is opened, ,clicking on the Select button in the Action column of the grid for the chosen option.

Required Steps

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

• The API needs to be set up correctly. See the Set Up section.

• The Invoice needs to have a Customer selected

• The address in the Address tab needs to be valid. It can be validated by Validate button in the Shipping tab.

• An Internal Contact needs to be selected.

• The Site ID for the Branch the Internal Contact belongs to needs to be valid. 

• A Contact Person needs to be selected, even if contact info is to be excluded. [TODO - disable this check if contact is not required by GoSweetSpot]

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

  Field	Description	Example
  Address Line 1	The building name  (Optional)	Unit 2
  Address Line 2	The street address	46 Bracken Place
  Address Line 3	The suburb	Avonhead
  Address Line 4	The city	Christchurch

  If the building name is ommitted then Line 1 becomes the street address and the other lines are moved up with it.
  
  

• From the Parcel Selection grid accessed from the Shipping Tab, there needs to be at least one parcel created, with dimensions and a weight or a name matching a GoSweetSpot pre-loaded name, and without a tracking number or shipping number. 
  

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

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

• Changes to the Invoice outside of the Shipping tab need to be saved. Unsaved information is not sent to GoSweetSpot. 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 a tracking email will be sent to the email address of the delivery contact.

• If the Signature checkbox is checked, then the delivery is required to be signed for.
• If the Saturday checkbox is checked, then the delivery will be scheduled for Saturday, which may substantially increase the cost of delivery.

• Special instructions for delivery can be set from the Shipping Tab in the Delivery Instructions field.

• If the Order Number field in the Detail Tab is set then this becomes the reference printed on the label. 
  

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, GoSweetSpot Delivery Options, with a list of the available rates or Delivery Options and their costs and other relevant information. 

Clicking a Select button will create a shipment with GoSweetSpot with the option for the row.

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 GoSweetSpot, then a success message with details for the created shipment will appear.

When the success message is dismissed, the parcel labels will be automatically downloaded by the browser as a PDF file. This file will also be saved as an attachment 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.

The tracking number will 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.

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 GoSweetSpot will be 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 Tracking Number and Tracking URL for the shipment will be set.

• The API Status column remains empty but can now be updated by selecting a row and clicking the Status button.

Attachments

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

[TODO] The attachments added for the created shipment will include the name of the Courier Delivery company, for example "GoSweetSpot", and the tracking number in their names.

Delivery Status Updates

The Delivery Status for the last created shipment belonging to the Invoice can be updated 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. This feature is currently only available from Invoice forms.