Internet Shipment Format (ISF) specification

Learn about the underlying standards and check out the full Internet Shipment Format specification

Basic information

File structure

An ISF file is made of a collection of events related to online trade - orders and returns.

Each event (order or return) consists of:

  • a shipment containing one or more parcels
  • sender information
  • recipient information
  • payee information
  • return to sender information
  • error information (if any occur)

Each shipment consists of the following elements:

  • tracking number and link
  • parcels (one or more)
  • shipment label
  • courier service type (i.e. priority, time of delivery)
  • additional service information
  • services related to shipment collection
  • sender cost

Each parcel consists of:

  • tracking information
  • parcel details (packaging type, weight, dimensions, contents, references)

Each shipment contains information neccessary to print a shipping label, appropriate to the shipment type, as well as gives the ability to include return information (if required by courier):

  • shipment number
  • parcel number(s)
  • tracking link
  • label
  • return shipment (RS) label

Standards used

The following open data standards are used for some ISF elements:

  • currency, according to ISO 4217 - e.g. GBP, USD, EUR
  • language, according to ISO 639-2 - e.g. eng, pol, deu=ger
  • country, according to ISO 3166-1 alpha-2 - e.g. GB, US, DE
  • subdivision (region), according to ISO 3166-2 - e.g. PL-ZP, US-DC, DE-BB
  • time (generated), according to ISO 8601 - e.g. 2016-05-25T11:08:51+01:00

ISF protocol (web service)

To enable handling orders via the ISF web service, a shop needs to configure the following:

  • web service URL
  • secret key password
  • user name (optional)

Web service hash algorithm

$isf - ISF data (XML)
$time - current timestamp
$key - secret key, known to the courier and the shop ("Secret key")
$user - user name
$isfHash - $isf hashed with SHA-256

  • the request hash is calculated as SHA-256 from concatenated data (with no extra characters in between): $user, $isfHash, $key and $time
  • request should be formatted as JSON and sent as POST

Example:

$isfHash = hash('sha256', $isf);
$time = time();
$requestHash = hash('sha256', $user . $isfHash . $key . $time);
$contents = array(
    'user' => $user,
    'isf' => $isf,
    'time' => $time,
    'hash' => $requestHash
);

Sample ISF 1.1 files

Full technical specification

Older versions