📋 Standard data format

Below are the standard data types and constraints used by the Ship24 API. Except if specifically mentioned, they are valid for any request and response. Your request will be rejected if the data doesn't comply with it.

Data format

Logistics date and time

In logistics, tracking events' date/time precision and representation vary from one courier to another. Ship24 aims to provide an easy-to-use, unified and ISO-8601-compliant format to represent those logistic dates, without compromising on precision.

Couriers often provide the events' date and time in local time related to the event's location or their headquarters, and sometimes the associated time-zone information. In some cases, only the UTC date is available from the courier, and in rare cases, only the date is provided, without the exact time of the day.

In the API, fields containing datetime in their names (for example, occurrenceDatetime, infoReceivedDatetime, etc.) refer to this logistics data, and time format should be interpreted as below:

Value (ISO-8601-compliant)	Description
2022-10-23T15:13:37	Sun Oct 23 2022 15:13:37 local time/courier time
2022-12-21T17:01:12+02:00	Wed Dec 21 2022 17:01:12 local time/courier time which is on a GMT+02:00 time zone . Equivalent to Wed Dec 21 2022 15:01:12 UTC
2022-09-03T23:58:12Z	Sun Sep 04 2022 23:58:12 UTC time (time zone of occurrence of the event not provided)
2022-08-14	Sun Aug 14 2022 during the day, local time

In any case, being ISO-8601-compliant, parsing those types of fields will result in a valid Date.

Note1: In case the time of the day is not available (values such as 2022-08-14), a field order is present to help you order the events if required (lower is older).

Note2: In the events objects of the Tacking API, the fields datetime, utcOffset and hasNoTime are deprecated and replaced by the unified occurrenceDatetime field.

Other date and time

All other dates in the API, usually containing At in their names (for example, generatedAt, createdAt, etc.), are expressed in UTC and are strings in the ISO 8601 "combined date and time representation" format, such as 2019-05-15T15:50:38Z.

Tracking number

A tracking number must have a length between 5 and 50 characters. Only the following characters are supported: A - Z, a - z, 0 - 9, - (Hyphen), _ (Underscore), / (Slash), and . (Period). Dummy tracking numbers such as 123456789, TEST123, 00000 will be rejected. If you notice our API is rejecting a valid tracking number, please contact us.

Note: Even if given in lowercase, the tracking number will be transformed to uppercase in all API responses and webhooks. Therefore, we advise API consumers not to use case sensitivity when comparing tracking numbers.

Country code

Our API always returns country codes in ISO 3166-1 alpha-2 format (e.g. FR, DE, CN). Our API only accepts ISO 3166-1 alpha-2 or alpha-3 format in the requests. (e.g. FR, FRA, DE, DEU, CN, CHN)

Postcode

A postcode most have a length between 1 and 32 characters. Only the following characters are supported: A - Z, a - z, 0 - 9, - (Hyphen), (Space), . (Period), _ (Underscore), / (Slash).

API evolution

Ship24 will always ensure the retro-compatibility of the API, in other words, existing fields never will be removed or modified. However, some fields may be marked as deprecated and new fields may be added along the way.

Deprecated fields

The following fields are deprecated but kept in the API for retro-compatibility.

Field	Depreciation date	Alternative
datetime	2022-12	occurrenceDatetime
utcOffset	2022-12	occurrenceDatetime
hasNoTime	2022-12	occurrenceDatetime