Integrations Spec

• 1. Introduction
• 2. Revision history
  • 2.1 TODO
• 3. Shiip API web services
  • 3.1. Overview
    • 3.1.1. Features
    • 3.1.2. Service details
    • 3.1.3. Environments and URIs
    • 3.1.4. Authentication
  • 3.2. Authentication Token
    • 3.2.1. Authentication parameters
    • 3.2.1. Request
    • 3.2.2. Response
    • 3.2.3. Example response
    • 3.2.4. Using the authentication token response
  • 3.3. Create Shipment
    • 3.3.1. Basic Request
      • 3.3.1.1. Structure
      • 3.3.1.2. Shipment object parameters
      • 3.3.1.3. Address object parameters
      • 3.3.1.4. Goods object parameters
      • 3.3.1.5. Dangerous Goods object parameters
      • 3.3.1.6. Additional Services
      • 3.3.1.7. Vehicle Preference Options
      • 3.3.1.8. Auto-Manifest Options
      • 3.3.1.9. Reassignment Options
      • 3.3.1.9. Originating System Options
    • 3.3.2. Response
      • 3.3.2.1. 200 OK
      • 3.3.2.2. 400 Bad Request
    • 3.3.3. Example request
    • 3.3.4. Example response
  • 3.4. Get Estimates
    • 3.4.1. Request
      • 3.4.1.1. Structure
      • 3.4.1.2. Shipment object parameters
      • 3.4.1.3. Address object parameters
    • 3.4.2. Response
      • 3.4.2.1. 200 OK
    • 3.4.3. Usage of the Get Estimates response
  • 3.5. Cancel Shipment
    • 3.5.1. Request
      • 3.5.1.1. Structure
      • 3.5.1.2. Parameters
    • 3.5.2. Response
      • 3.5.2.1. 200 OK
  • 3.6. GetEventsByShipmentNo
    • 3.6.1. Request
      • 3.6.1.1. Structure
      • 3.6.1.2. Parameters
    • 3.6.2. Response
      • 3.6.2.1. 200 OK
        • 3.6.2.1.1. Structure
        • 3.6.2.1.2. Attributes
        • 3.6.2.1.3. Example
  • 3.7. Get Proof of Delivery
    • 3.7.1. Request
      • 3.7.1.1. Structure
      • 3.7.1.2. Parameters
    • 3.7.2. Response
      • 3.7.2.1. 200 OK
  • 3.8. Get Labels
    • 3.8.1. Request
      • 3.8.1.1. Structure
      • 3.8.1.2. Parameters
      • 3.8.1.3. Label Types
    • 3.8.2. Response
      • 3.8.2.1. 200 OK
  • 3.9. Load Shipment On Vehicle
    • 3.9.1. Request
      • 3.9.1.1. Structure
      • 3.9.1.2. Parameters
    • 3.9.2. Response
      • 3.9.2.1. 200 OK
  • 4. Manifest By ShipmentNo
    • 4.1.1. Request
      • 4.1.1.1. Structure
      • 4.1.1.2. Parameters
    • 4.1.2. Response
      • 4.1.2.1. 200 OK
• 5. Create Shipment CSV service
  • 5.1. Overview
    • 5.1.1. Features
    • 5.1.2. Service details
    • 5.1.3. Authentication
  • 5.2. Shipment CSV specification
    • 5.2.1. Structure
    • 5.2.2. Columns
  • 5.3. Additional Notes
• 6. Webhook tracking event service
  • 6.1. Overview
  • 6.2. Features
  • 6.3. Service details
  • 6.4. Request
    • 6.4.1. Structure

1. Introduction

The purpose of this document is to outline the guidelines and specifications required to integrate external systems with Shiip.

Shiip's integration capabilities can broadly be classified into the following functions:

• Freight cost estimates
  • Automatically request freight quotes directly from Shiip's estimates system.
  • Examples of use:
    • Retrieve freight estimates to provide more accurate shipping costs to customers - eg. "Boutique Gifts" web store wants to provide shipping cost estimates for the Shiip same day shipping option.
      • Your development team could write an addition to the web store that uses Shiip Estimates API to display a shipping cost based on the Shiip Estimate.
      • Your team would be able to get estimates for all of your Shiip based carriers using one API call to one source instead of trying to
• Creating shipments
  • Integration with the Create Shipment systems can be used to create shipments automatically.
    • Shipments can be created in a draft state for a user to complete.
      • This is required where you do not have all the freight details immediately, eg. you may need your despatching staff to enter dimensions manually if they are packing multiple items into a carton.
      • It can also be useful if your orders are importing automatically but your despatching staff plan to make the shipments "Ready" as they work through the list.
    • Shipments can be created in a ready state that is immediately ready to print.
      • This option does require that all of the shipment details be available and correct.
      • Printing can also be set up to happen automatically if it suits the desired workflow.
  • Examples of use:
    • Create and print shipments from your own CRM - eg. "Sven's Stationary" wants to be able to create shipments from orders in their CRM software.
      • A developer could implement a button on the CRM software that would make use of Shiip's Create Shipment API to create a shipment with the correct receiver and line item details.
      • By setting up Shiip's air print system these labels can then be printed automatically when the user finalizes an order in their existing CRM software.
    • Import orders as shipments for processing - eg. "Boutique Gifts" offers some products for sale on an eBay store and would like to import their orders daily for processing.
      • Using the order export capability on the eBay store, they extract a CSV containing the receiver details for each order. The CSV is then uploaded into Shiip for processing.
      • Shiipprocesses the CSV and creates Draft shipments which contain the receiver's details without the need for the user to enter them one by one.
      • A user can then open the drafts one by one, gather the ordered items, pack them into a box, enter the dimensions and then label the freight before moving onto the next order.
• Cancelling shipments
• Reassigning shipments
• Manifesting Freight
• Downloading labels
  • Allows an external system to download the labels instead of printing directly from Shiip.
  • Examples of use:
    • You are printing labels to multiple printers and have internal logic that determines which labels need to go where. Your system could then download the label and route it to the appropriate printer or warehouse.
• Tracking shipments
  • Allows you to track your shipments using the same system for multiple carriers.
  • Examples of use:
    • Updating CRM with shipment numbers - eg. "Sven's Stationary" require a shipment number and despatch date against every customer order in their CRM software.
      • They have been extracting a daily report of all shipments despatched at the end of the day and manually entering the shipment information into their CRM.
      • With a little development effort and Shiip Event Webhooks, they are able to rid themselves of this manual process by setting up a “Despatched” event callback in Shiip. Whenever a shipment reaches the “Despatched” status, Shiip Event Webhooks calls Sven’s API and sends the customer name, order reference, shipmentNo and despatch date, which then updates the customer CRM record in real-time.
    • Late delivery follow up - "Boutique Gifts" offers a next day delivery service via their web store checkout.
      • With the help of an external developer and Shiip Event Webhooks, Boutique Gifts extend their eCommerce platform to check for any carrier delays on their priority orders.
      • Shiip Event Webhooks calls their API whenever a priority shipments “Despatched” and “In Transit” events are updated. Boutique Gifts can now check for any changes in the shipment’s ETA value.
      • If the ETA shows that the delivery has been delayed, Boutique Gifts can proactively reach out to their customer to make alternative delivery arrangements (time permitting) or offer a gift card as compensation.

There are two methods presented in this spec with which a client can integrate with Shiip, a REST based web API service, and a CSV file upload service. Generally the API service is recommended as it affords better error handling capabilities, however file upload integration is also available to accomodate compatability with existing or legacy systems.

2. Revision history

• 2023-07-17
  • Added Demo and Production endpoint URIs
  • Added further use cases to API features
  • Added further use cases to Get Estimates
  • Added Dangerous Goods object params
  • Added Additional Services attributes and use cases
  • Added Vehicle Types attributes and use cases
  • Added Reassignment attributes and use cases
  • Added Originating System options and use cases
  • Added costcenter, orderNo, and originator attributes to shipment object
  • Added Cancel Shipment endpoint
  • Added Get POD endpoint
  • Added Manifest by ShipmentNo endpoint
  • Added Load Shipment On Vehicle endpoint
  • Revised Get Labels endpoint to include supported formats
  • Revised Get Labels endpoint to include label retrieval by item reference
  • Added limitResults and sortBy attributes to Get Estimates endpoint
  • Added TODO section
  • Various semantic edits and tidy up
• 2021-08-25
  • Added labelPrinter to CSV import
• 2021-08-24
  • Added intro section with examples of functionality
  • Added labelPrinter and additionalCharges parameters
• 2021-02-15
  • Added explicit examples of UOMs
  • Fixed some typos
• 2021-02-02
  • CreateShipment payload updated with additional properties
• 2021-01-14
  • GetEstimates endpoint path updated
• 2020-12-30
  • Fixed a broken link
• 2020-11-24
  • Deprecate old CSV format, added new CSV spec
• 2020-10-10
  • Added shipment tracking endpoint
• 2020-10-09
  • Added Webhook tracking event service
• 2020-10-08
  • Added carrierCode and serviceCode parameters to CreateShipment spec
• 2020-09-07
  • Deprecated Reference parameter
• 2020-08-11
  • Added ReceiverReferences and SenderReferences parameters
  • Added GetEstimates spec and corresponding shipmentNo parameter to CreateShipment when using an estimate
• 2020-03-02
  • Added CSV upload service
• 2019-07-04
  • Initial public API spec

2.1 TODO

• Add Required Additional Fields to Additional Services object params
• Add Get Locations endpoint
• Add Create Location endpoint
• Add dangerous goods usage examples to Create Shipment sample request
• Add more complete Create Shipment sample response

3. Shiip API web services

3.1. Overview

The Shiip API web service is a RESTful suite of web services that allows an authenticated Shiip client to consume and interact with various Shiip features and functionality programatically. The Shiip Web Services are typically used for bespoke integrations and interactions via first and thrid party customer software and services.

3.1.1. Features

• Create shipments across multiple carriers and services via REST or legacy SFTP services
• Create courier and same day last mile bookings across multiple providers
• Retrieve cost estimates for a given freight movement and create a shipment / job booking from the selected results
• Request and filter carriers based on additional service requirements including vehicle types, delivery attributes and delivery add-ons
• Reassign shipments and courier jobs from one carrier to another
• Fetch and print labels, shipments and other related documentation in a variety of formats
• Cancel shipments and job bookings
• Manifest and auto-manifest shipments
• Track and trace shipmentsand last mile jobs
• Fulfill eCommerce orders automatically upon freight despatch
• Utilise webhooks to add event driven logic to your own integrated systems

3.1.2. Service details

The Shiip API web service is a REST based web service with a variety of endpoints that accept serialised JSON request objects. The service is compatible with and intended to be used by REST based clients over HTTPS.

Request payload structure is presented in JSON format, the user is expected to understand JSON syntax - including the format of any required array parameters, quoting and escaping on string values, and omitting quotes on number values.

3.1.3. Environments and URIs

Shiip has two environments available for consumption of the APIs outlined in this document.

Shiip Demo environment - This is a sandboxed environment that always contains an identical feature set to the Shiip Production environment. The Demo environment is a non-live environment that should be utilised for initial integration development and testing before using the Shiip Production environment.

The Shiip Demo environment base URI is https://demo.api.shiip.com.au/

Shiip Production environment - This is Shiip's live environment where any API interactions will result in stateful real world changes.

The Shiip Production environment base URI is https://prod.api.shiip.com.au/

3.1.4. Authentication

The service is secured via 0Auth 2.0 authentication using JSON Web Tokens (JWT). A connecting client must authenticate with a valid and active Shiip login/password combination and WMS Code to request an access token, which is then used to authenticate with Shiip web services.

3.2. Authentication Token

3.2.1. Authentication parameters

3.2.1. Request

POST /TokenByWmsCode

{
  "email": string,
  "password": string,
  "wmsCode": string
}

3.2.2. Response

{
  "access_token": string
}

3.2.3. Example response

{
  "access_token" : "Bearer E/04rkIMJYuBZYi5hLmVqDYqo9Ew+epZ0lkVE3ylAhGoOzKgm1P8Oh258gwu396VgJ8ftIR1XYvhJYM2T7s0Fe2qAEq2ZE95qSgU7aQLu32BmYGZzOLTQAi/Vbma+PMFf6pyXYf8dWYYEJoNAt6M4tua8/1qUzilza3FyfcjLpY5FMVt8kTXBsl3K8LfPlO12YuloAoZqiXv6PY9KGSrCeOqNoHqW5vOZ29S0tLkYvYkMnHnToh/HocexLse3iuMCxy9ZIr+Igs="
}

3.2.4. Using the authentication token response

The token may then be used in the "Authorization" header on subsequent requests to authenticate against all Shiip API endpoints.

Authorization: Bearer E/04rkIMJYuBZYi5hLmVqDYqo9Ew+epZ0lkVE3ylAhGoOzKgm1P8Oh258gwu396VgJ8ftIR1XYvhJYM2T7s0Fe2qAEq2ZE95qSgU7aQLu32BmYGZzOLTQAi/Vbma+PMFf6pyXYf8dWYYEJoNAt6M4tua8/1qUzilza3FyfcjLpY5FMVt8kTXBsl3K8LfPlO12YuloAoZqiXv6PY9KGSrCeOqNoHqW5vOZ29S0tLkYvYkMnHnToh/HocexLse3iuMCxy9ZIr+Igs=t

3.3. Create Shipments

This API accepts a single shipment object and returns either a success message or list of errors.

• By default the Create Shipment endpoint will create a Draft shipment which a user can then then access via the Shiip frontend to fill in any additional or missing details before saving the completed shipment number.
• Alternatively a location can be set to create shipments in a Ready state by auto-selecting either the cheapest, fastest or a preferred service (This can be set in Shiip Frontend > Settings > Connectivity). If there are no issues with the supplied data the shipment will be created in a Ready state and will be available to print and manifest without the user having to select the carrier or service themselves.
• For a more complete integration you can also use Get Estimates to display or process the estimates on your system and then issue a corresponding Create Shipment request to select and finalise one of available estimates.
• Not all of the shipment details are required for a shipment to be created in an Incomplete state, but the shipment does need to be complete in order to be created in a "Ready" or "Booked" state. This can be completed by finalising the draft from the Shiip Frontend.
  • for example to create a complete shipment which is ready to be despatched:
    • supply the complete shipment details via the Create Shipment API so that the shipment is ready immediately
    • supply goods line(s) with the Quantity and an ItemReference that matches an item in your Shiip Product List - allowing Shiip to fill in the dimensions and make the shipment ready
  • or to create an incomplete shipment that a user will finalise later via the Shiip Front End:
    • supply goods line(s) with dimensions but no weight or vice versa
    • supply only the sender and receiver details and no goods etc.

3.3.1. Basic Request

POST /Shipment/CreateShipment

3.3.1.1. Structure

{
  "readyDateTime": string,
  "customerCode": string,
  "warehouseCode": string,
  "senderReferences": [
    string
  ],
  "receiverReferences": [
    string
  ],
  "senderAddress": {
    "CompanyName": string,
    "Address1": string,
    "Address2": string,
    "Suburb": string,
    "State": string,
    "PostCode": string,
    "Country": string,
    "Contact": string,
    "Phone": string,
    "Email": string
  },
  "receiverAddress": {
    "CompanyName": string,
    "Address1": string,
    "Address2": string,
    "Suburb": string,
    "State": string,
    "PostCode": string,
    "Country": string,
    "Contact": string,
    "Phone": string,
    "Email": string
  },
  "emailTracking": [
    string
  ],
  "shipmentGoods": [
    {
      "ItemReference": string,
      "Qty": int,
      "Weight": float,
      "Length": float,
      "Width": float,
      "Height": float,
      "UnitOfMeasureName": string
    }
  ],
  "specialInstructions": string,
  "additionalCharges": [
    string
  ]
  "serviceCode": string,
  "labelPrinter": string,
  "accountNo": string",
  "addToAddressBook": boolean,
  "saveAsDraft": boolean,
  "reassignedFrom": string,
  "reason": string,
  "autoManifest": boolean,
  "autoManifestDateTime": string,
  "costCentre": string,
  "orderNo": string,
  "vehicleType": string,
  "originator": string,
  "preferredJourney": boolean
}

3.3.1.2. Shipment object parameters

* The applicable carrier and service codes will be provided on request. The list of supported carriers is constantly changing and carriers can add/change their services at any time so providing a static list is infeasible.

3.3.1.3. Address object parameters

3.3.1.4. Goods object parameters

3.3.1.5. Dangerous Goods object parameters

• It is mandatory to declare any dangerous goods that will be travelling on a given shipment. For a preliminary understanding of dangerous goods, including the associated classes, UN numbers and packaging requirements, please refer to https://www.ntc.gov.au/codes-and-guidelines/australian-dangerous-goods-code as a primer.

3.3.1.6. Additional Services

The following additional services / delivery requirements may be specified in either a Create Shipment or Get Estimates request.

• Not all carriers and services can accomodate all the additional services below. If specifying additional services via a Create Shipment request, please double check that the carrier can provide the additional services required.
• If additional services are requested as part of a Get Estimates request, the results will be filtered to return only carriers and services that can accomodate the additional services specified in the request
• Some additional services require supplemental information to be provided as an array of "additional fields" objects. This supplemental information is specified in the Additional Fields column of the object parameters table below (TODO).
• Additional Services must be specified as an array of objects on the "additionalServices" attribute using the following JSON structure

"additionalServices": [
    {
      "serviceCode": "string",
      "additionalFields": [
        {
          "name": "string",
          "value": "string/int/boolean"
        }
      ]
    }
]

Additional Services object parameters

3.3.1.7. Vehicle Preference Options

Certain carriers and couriers allow specifying a preferred vehicle type for delivery. This can be convenient for small deliveries (such as requesting a bike for short inner city movements) or ensuring a large capacity vehicle is used for bulk freight movements. If not specified, the Vehicle Type will default to the standard vehicle type used with the corresponding carrier service.

• If the vehicleType attribute is used in a GetEstimates request, only carriers and services that provide a matching vehicle type will be returned.

3.3.1.8. Auto-Manifest Options

Shiip provides the ability to automatically manifest shipments if the "autoManifest" attribute is set to "true".

• By default if a shipment is flagged to auto manifest, it will immediately manifest (transmit data to the carrier) when its "readyDateTime" is reached.
• The optional "autoManifestDateTime" attribute can be used to specify a ISO dateTime to set the desired date and time for the manifesting event to occur. If more than one shipment is created with the same autoManifestDateTime attribute, those shipments will be manifested together under the same manifest number.

3.3.1.9. Reassignment Options

Shiip provides the ability to reassign shipments and courier jobs between carriers.

• A shipment may only be reassigned to another carrier if it has not yet been manifested and is not in "Incomplete" status
• A courier (or same day job) may only be reassigned to another carrier if it has not yet been collected and is not in an "Incomplete" status
• If the "reassignFrom" attribute is utilised in a Get Estimates request, the carrier/service on the original shipment to be reassigned will be omitted so that the same service cannot be reselected
• When using the reassignment workflow, the original shipment (shipment to be reassigned) will be cancelled. A new shipment replacing it will be created separately and will automaticlly inherit the same sender, receiver, goods details and other relvant attributes. The new shipment will be assigned a new shipment number which can be matched between both old (unassigned) and new (reassigned) shipment via the additional attributes outlined below.

Reassigning a shipment or courier job requires the following attributes to be utilised in a Create Shipment request:

When a shipment has been sucessfully reassigned, the following attributes will be available on the original shipment object that was reassigned:

  "reassignedTo": string,
  "reassignedToCarrier": string,
  "reassignedToService": string,
  "reassignedReason": string

The new shipment (replacing the old one) will contain the following attributes:

  "reassignedFrom": string,
  "reassignedFromCarrier": string,
  "reassignedFromService": string,
  "reassignedReason": string

3.3.1.9. Originating System Options

Shiip provides some out of the box functionality for common integrated system workflows (at this time eCommerce platforms) based on the "originator" attribute present on a Shipment object. This attribute may also be utilised for convenience in combination with Shiip webhooks to track and trigger custom workflows via your own integrated systems.

The following values may be set on the "originator" attribute to activate supplemental workflows via supported integrated systems:

• To utilise this attribute to configure workflows on a supported integrated platform, please contact Shiip Support.

3.3.2. Create Shipment Response

3.3.2.1. 200 OK

{
  "shipmentNo": string,
  "manifestNo": string,
  "status": string,
  "TrackingUrl": string,
  "carrierName": string,
  "serviceName": string,
  "ETA": string,
  "reassignedFrom": string
}

3.3.2.2. 400 Bad Request

{
  "errors": {
    "ReceiverAddress.State": [
      "The State field is required."
    ]
  },
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-3917ede038dca84a988e14a9ed613671-b13171b872ea184f-00"
}

3.3.3. Example request

{
  "CustomerCode": "TMS3PL",
  "WarehouseCode": "N04",
  "SenderReferences":[
    string
  ],
  "ReceiverReferences":[
    string
  ],
  "ReceiverAddress": {
    "CompanyName": "Acme Industries",
    "Address1": "9-12 Test Street",
    "Address2": "",
    "Suburb": "Acme South",
    "State": "QLD",
    "PostCode": "4008",
    "Country": "Australia",
    "Contact": "",
    "Phone": "0733300333",
    "Email": "wile.e.coyote@acme.com.au"
  },
  "EmailTracking": [
    "wile.e.coyote@acme.com.au",
    "manager@acme.com.au"
  ],
  "ShipmentGoods": [
    {
      "ItemReference": "STW9C2N-EU",
      "Qty": "4",
      "UnitOfMeasureName": "Pallet",
      "Weight": 5,
      "Length": 12,
      "Width": 20,
      "Height: 12
    }
  ],
  "SpecialInstructions": "Beware of the dog"
}

3.3.4. Example response

{	
  " shipmentNo": "Draft-1P82D",
  "manifestNo": "",
  "status": "Incomplete"
  "TrackingUrl": ""url"",
  "carrierName": "",
  "serviceName": "",
  "ETA": ""
}

{
  " shipmentNo": "TEST01342",
  "manifestNo": "20191220001",
  "status": "Ready"
  "TrackingUrl": "https://path/to/trackingNo",
  "carrierName": "Startrack Express",
  "serviceName": "FPP",
  "ETA": "2020-07-24T00:00:00"
}

3.4. Get Estimates

This service allows clients to request a list of available carriers, services and price estimates for a given sender, receiver and goods combination. Results can be optionally sorted and truncated using "sortBy" and "limitResultsTo" parameters.

The service returns an array of Carrier/Service objects which can optionaly be identified by a temporary corresponding draft ‘ShipmentNo’. The draft shipmentNo from the returned object can then be used as the sole parameter in a CreateShipment request to convert a selected estimate into an ‘Incomplete' or ‘Ready’ shipment. or a "Booked" courier job in Shiip.

• Note: To enable inclusion of the temporary draft shipmentNo attribute, the "createDrafts" boolean must be present and set to "true" in the Get Estimates request (see below).

3.4.1. Request

POST /Estimate/GetEstimates

3.4.1.1. Structure

The GetEstimates request follows the same request structure and attributes as the CreateShipment request, with the following additions/changes:

3.4.1.2. Shipment object parameters

3.4.1.3. Address object parameters

• Unlike a Create Shipment request, the carrierName and sericeName attributes are not specified in a Get Estimates request and will be ignored.

3.4.2. Get Estimates Response

3.4.2.1. 200 OK

[
  {
    "shipmentNo": "Draft-33AVH",
    "account": "TMS123",
    "carrierName": "Allied Express",
    "serviceName": "Road Express",
    "price": "14.68",
    "eta": "2020-07-24T00:00:00",
    "minEta": "0001-01-01T00:00:00"
  },
  {
    "shipmentNo": "Draft-LITMW",
    "account": "30512344",
    "carrierName": "TNT Express",
    "serviceName": "Road Express",
    "price": "30.18",
    "eta": "2020-07-24T00:00:00",
    "minEta": "0001-01-01T00:00:00"
  },
  {
    " shipmentNo ": "Draft-JO5ZM",
    "account": "112123438",
    "carrierName": "Couriers Please",
    "serviceName": "Express I55",
    "eta": "2020-07-24T00:00:00",
    "minEta": "0001-01-01T00:00:00"
  },
  {
    " shipmentNo ": "Draft-TERVX",
    "account": "TMSFSD",
    "carrierName": "BlueStar Logistics",
    "serviceName": "Exp Plt - 2.2 High To Town",
    "eta": "2020-07-24T00:00:00",
    "minEta": "0001-01-01T00:00:00"
  }
]

3.4.3. Usage of the Get Estimates response

The estimates response can be used as it is to display approximate quotes or do calculations.

To subsequently create a shipment based on a selected estimate, a value of "true" can be set on the "createDrafts" attribute of the Get Estimates request. The response will include the "shipmentNo" property on each service returned which may then be supplied to the CreateShipment endpoint as follows:

POST /Shipment/CreateShipment

{
  " shipmentNo": "Draft-TERVX",
}

3.5. Cancel Shipment

This endpoint accepts a single shipmentNo string and returns a success or failure response indicating the successful or unsuccessful cancellation of the given shipment.

• Note: The API consumer must have suffient permissions to action a shipment cancellation request. Please check with Shiip Support if you are unsure if your account has the required permission.

3.5.1. Request

DELETE / Shipment /CancelShipment/{shipmentNo}

3.5.1.1. Structure

As a DELETE request there is no request payload, the shipment to cancel will be specified as the final path component of the request URI.

3.5.1.2. Parameters

3.5.2. Cancel Shipment Response

3.5.2.1. 200 OK

3.6. GetEventsByShipmentNo

This endpoint accepts a single shipment number and returns a history of any related shipment events that have occured to date

3.6.1. Request

GET /Shipment/GetEventsByShipmentNo/{shipmentNo}

3.6.1.1. Structure

As a GET request there is no request payload, the shipment will be specified as the final path component of the request URI.

3.6.1.2. Parameters

3.6.2. Response

3.6.2.1. 200 OK

3.6.2.1.1. Structure

{
    "shipmentNumber": string,
    "trackingStatus": string,
    "trackingLocation": string,
    "eta": string,
    "events": [
        {
            "status": string,
            "dateTime": string,
            "details": string,
            "location": string,
            "orderId": integer
        }
    ]
}

3.6.2.1.2. Attributes

Note that the status attributes provided in this response are normalised to Shiip statuses where possible so that API users do not have to handle carrier specific status responses.

Shipment object

Event object

3.6.2.1.3. Example

{
    "shipmentNumber": "TEST00005143",
    "trackingStatus": "In Transit",
    "trackingLocation": "BRISBANE, QLD",
    "eta": "28/01/2020 12:00:00 AM",
    "events": [
        {
            "status": "In Transit",
            "dateTime": "2020-01-27T16:03:23",
            "details": "Item(s) picked up from sender location",
            "location": "BRISBANE, QLD",
            "orderId": 1518386
        },
        {
            "status": "In Transit",
            "dateTime": "2020-01-28T14:12:08",
            "details": "Item(s) in transit",
            "location": "AP MOUNT ISA DC, QLD",
            "orderId": 1524557
        },
        {
            "status": "In Transit",
            "dateTime": "2020-01-28T14:10:16",
            "details": "Item(s) in transit",
            "location": "AP MOUNT ISA DC, QLD",
            "orderId": 1524556
        },
        {
            "status": "Despatched",
            "dateTime": "2020-01-27T14:45:13.1133333",
            "details": "Item(s) despatched to Startrack Express",
            "location": "TINGALPA, QLD",
            "orderId": 1
        }
    ]
}

3.7. Get Proof of Delivery

This endpoint accepts a single shipment number and returns a Proof of Delivery (POD) image.

3.7.1. Request

GET /Shipment/GetPod/{shipmentNo}

3.7.1.1. Structure

As a GET request there is no request payload, the shipment will be specified as the final path component of the request URI.

3.7.1.2. Parameters

3.7.2. Get POD Response

3.7.2.1. 200 OK

HTTPS response returning an image in JPEG format.

3.8. Get Labels

This endpoint accepts an array of shipment numbers and an optional array of item reference numbers and will return the corresponding labels in the format specified.

3.8.1. Request

POST /Print/GetLabelsByType/{labelType}

3.8.1.1. Structure

[
  {
    "shipmentNo": "string",
    "itemReferences": [
      "string",
      ...
    ]
  },
  {
    "shipmentNo": "string",
      "itemReferences": [
        "string",
        ...
      ]
  },
  ...
]

3.8.1.2. Parameters

3.8.1.3. Label Types

The following label formats are supported and can be requested by specifying the labelType in the URI

3.8.2. Get Labels Response

3.8.2.1. 200 OK

HTTPS response specifying the corresponding content-type and body containing the application data stream.

3.9. Load Shipment On Vehicle

This endpoint accepts a single shipment number and flags it as being loaded on the delivery vehicle prior to manifesting

3.9.1. Request

PUT /Shipment/Loadshipment/{shipmentNo}

3.9.1.1. Structure

As a PUT request there is no request body, theshipmentNo will be specified as the final path component of the request URI.

3.9.1.2. Parameters

3.9.2. Response

3.9.2.1. 200 OK

4. Manifest By ShipmentNo

This endpoint accepts a single manifest number and returns a success or failure response indiciting the successful or unsucesful transmission of shipment data to the assigned carrier.

4.1.1. Request

PUT /Shipment/ManifestByNo/{shipmentNo}

4.1.1.1. Structure

As a PUT request there is no request body, the manifestNo will be specified as the final path component of the request URI.

4.1.1.2. Parameters

4.1.2. Manifest By ShipmentNo Response

4.1.2.1. 200 OK

5. Create Shipments CSV service

5.1. Overview

Clients can submit shipment data in a CSV format via a SFTP server, which is then accessible as an Incomplete (draft) shipment in Shiip.

5.1.1. Features

• Accepts one or more shipments per file and creates shipments in Shiip
• Creates the shipment in the appropriate Shiip tenancy based on authentication
• Can assign a default carrier to the shipment or create as draft based on location settings

5.1.2. Service details

The Create Shipment CSV Service operates as a standard SFTP server.

The client will need to connect to the SFTP server, authenticate, and then upload 1 or more CSV files matching the provided specification.

If your client implementation requires an absolute path, the upload path is /incoming - in most cases specifying an upload path is not required, the server will attempt to put the client in the incoming directory by default.

5.1.3. Authentication

A client connecting to the Shiip SFTP host must authenticate with a valid and active SFTP login/password combination (which will be provided by the Shiip team).

5.2. Shipment CSV specification

5.2.1. Structure

See also: sample CSV file

The CSV file should contain the shipment details for 1 or more shipments with all the shipment details that you wish to import.

• You can generate one file per shipment or multiple shipments per file.
• The first row should have headings that match the below column list for any details you need to import.
• Each shipment will consist of at least 1 row in the CSV file.
  • If a shipment has multiple lines of goods, then additional goods details can be added on subsequent rows.
  • These will be added to the preceding shipment as long as the sender/receiver details are either blank, or perfectly match the previous shipment.
• The start of the next shipment will be indicated by a row with address details or sender/receiver references that don't match the previous shipment.
• Columns that you don't need to fill in can be left blank, or the column can be left out entirely.

Column requirements can vary:

• Certain columns are required to create a shipment otherwise it can't exist, these are marked as required below.
• Other columns can be left blank if you want to create an incomplete shipment(eg. you might receive an order for 2 items, but the warehouse might pack them in one carton).
• Certain carriers may have stricter requirements than others (eg. Couriers Please requires the receiver contact details to be provided).
• If any required columns are left out or have invalid input, they will have to be entered/corrected by a user on the Shiip frontend before they can save and print the labels.

5.2.2. Columns

5.3. Additional Notes

• Mapping to your existing output format may be possible on a case by case basis.
• Legacy protocols may be available on a case by case basis.

6. Webhook tracking event service

6.1. Overview

The Webhook tracking event service facilitates the Shiip system providing live, event driven tracking updates for use by your developed applications.

6.2. Features

• Sends a full shipment payload including trackging event history when the status of a relevant shipment changes

6.3. Service details

A user can provide one or more endpoint URLs, nominate one or more events, and select which attributes to send in the payload. This is configured in the Shiip front end via Settings > Connectivity > Webhooks. When the status of a relevant shipment changes, Shiip will send a HTTPS request with the user's selected payload to the provided URL.

6.4. Request

6.4.1. Structure

{
  " shipmentNo": string,
  "carrierName": string,
  "serviceName": string,
  "estimatedPrice": string,
  "eta": string,
  "minEta": string,
  "accountNo": string,
  "senderAddress": {
    "companyName": string,
    "address1": string,
    "address2": string,
    "suburb": string,
    "state": string,
    "postCode": string,
    "contact": string,
    "phone": string,
    "email": string,
    "country": string
  },
  "reference": string,
  "senderReferences": [
    string
  ],
  "receiverReferences": [
    string
  ],
  "receiverAddress": {
    "companyName": string,
    "address1": string,
    "address2": string,
    "suburb": string,
    "state": string,
    "postCode": string,
    "contact": string,
    "phone": string,
    "email": string,
    "country": string
  },
  "shipmentGoods": [
    {
      "itemReference": string,
      "qty": int,
      "length": float,
      "width": float,
      "height": float,
      "weight": float,
      "unitOfMeasureName": string
    }
  ],
  "specialInstructions": string,
  "serviceCode": string,
  "labelPrinter": string,
  "accountNo": string",
  "autoManifest": boolean,
  "autoManifestDateTime": string,
  "costCentre": string,
  "orderNo": string,
  "vehicleType": string,
  "originator": string,
  "reassignedTo": string,
  "reassignedToCarrier": string,
  "reassignedToService": string,
  "reassignedFrom": string,
  "reassignedFromCarrier": string,
  "reassignedFromService": string,
  "reassignedReason": string
  "events": [
    {
      "status": string,
      "dateTime": string,
      "details": string,
      "location": string
    }
  ]
}

EOF