NAV
shell

Introduction

Welcome to the OMNISHIP API Documentation!

The OMNISHIP API allows you to perform operations on the OMNISHIP system.

OMNISHIP Shipping API is built using REST principles which ensures predictable URLs that makes writing applications easy. This API follows HTTP rules, enabling a wide range of HTTP clients which can be used to interact with the API.

Every resource is exposed as a URL. The URL of each resource can be obtained by accessing the API Root Endpoint https://app.omniship.eu/api/{platform}/v1/.

For example the Shipments resource is reachable at https://app.omniship.eu/api/shipping/v1/shipments.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "https://app.omniship.eu/api/<platform>/v1/<resource>"
  -H "Authorization: Bearer FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"

Make sure to replace FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv with your API key.

OMNISHIP uses API keys to allow access to the API. You can create an API key within the OMNISHIP application.

In order to authenticate properly, please put Authorization: Bearer <API Access Token> in the request header. OMNISHIP expects for the API key to be included in every API requests to the server in a header that looks like the following:

Authorization: Bearer FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv

Rates

The Rates API allows you to request a list of shipping quotes for a prospective Shipment. The response will also indicate which Courier prices and transit times.

Request Rates

curl "https://app.omniship.eu/api/shipping/v1/rates"
  -X POST
  -H "Authorization: Bearer FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"
  -d '{
        "origin_address": {
          "postal_code": "1091 KP",
          "city": "Amsterdam",
          "country": "NL"
        },
        "destination_address": {
          "postal_code": "1000",
          "city": "Bruxelles",
          "country": "BE"
        },
        "parcels": [
          {
            "box": "test",
            "quantity": 3,
            "weight": 2.5,
            "weight_unit": "kilograms"
          }
        ],
        "incoterms": "DDU",
        "apply_shipping_rules": true
      }'

The above command returns JSON structured like this:

HTTP/1.1 201 Created
Content-Type:application/json;charset=UTF-8

{
  "rates": [
    {
      "carrier_id": "56ea6a76-26a8-4d4e-a649-fadff28d1832",
      "carrier_admin_name": "fedex_international_economy",
      "carrier_display_name": "FedEx International Economy",
      "carrier_description": "A cost-saving solution for your less time-sensitive deliveries. A reliable, door-to-door, Customs-cleared, service between Europe, the Middle East and the US.",
      "pickup_available": true,
      "min_delivery_time": 2,
      "max_delivery_time": 6,
      "shipment_charge": 10.84,
      "fuel_surcharge": 2.66,
      "currency": "EUR"
    },
    {
      "carrier_id": "7605c1fc-683d-4860-a010-8fda26f2a79a",
      "carrier_admin_name": "fedex_international_priority",
      "carrier_display_name": "FedEx International Priority",
      "carrier_description": "A highly reliable, express, time-definite, customs-cleared, door-to-door service for your worldwide packages up to 68kg per unit.",
      "pickup_available": true,
      "min_delivery_time": 1,
      "max_delivery_time": 3,
      "shipment_charge": 23.21,
      "fuel_surcharge": 4.2,
      "currency": "EUR"
    }
  ]
}

HTTP Request

POST https://app.omniship.eu/api/shipping/v1/rates

Arguments

Attribute Type Description
sender_id string optional ID of the sender Address object. The origin address for the shipment is set by this ID. If the sender id is omitted the origin_address attribute is required.
origin_address object required if the sender_id is not given. Address object that should be used as the origin address.
destination_address object required Address object that should be used as receiver address.
parcels array required Array of Parcel objects with package details for the shipment to be sent.
incoterms string optional The terms of sale of the Shipment. Valid values are DDP, DDU, DAP.
apply_shipping_rules boolean optional Lets the algorithm apply the shipping rules created in the OMNISHIP portal, for instance to exclude couriers. By default the value is true.

Address Object definitions:

Field Name
Type
Description

postal_code

string

required if Country is postal aware. Address postal code.

city

string

required Address city

state

string

required if Country has states. (US, CA, MX, IN)

country

string

required Address country code in Alpha 2 Format (ISO 3166-1)

Parcel definitions:

Field Name
Type
Description

box

string

optional Courier or Custom Box slug. Use the Boxes API Resource to retrieve a list of available boxes.

length

integer

optional The length of the parcel in cm

width

integer

optional The width of the parcel in cm

height

integer

optional The height of the parcel in cm

weight

float

required The weight of the parcel. By default the weight will be in kilograms, the weight can be set in grams by setting the weight_unit attribute

weight_unit

string

Optional The unit in which the weight is measured. Valid values are: kilograms, grams. Default is kilograms

quantity

integer

optional The quantity of parcels with the same measures. Default is 1

Shipments

The Shipment resource is used to create, list, update and delete Shipments.

A Shipment will not be confirmed or paid for until you buy the label. This can be done by calling the Buy Labels endpoint or by using the buy_label or buy_label_synchronous attribute in the Create Shipment request. Once you Buy Labels for a Shipment through the Label API, you will not be able to update or delete it.

Create a Shipment

curl "https://app.omniship.eu/api/shipping/v1/shipments"
  -X POST
  -H "Authorization: Bearer FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"
  -d '{
        "platform_name": "AMAZON",
        "platform_order_number": "#1234",
        "reference": "shipment reference",
        "sender_id": "ecorp",
        "destination_address": {
          "contact_name": "Jane Doe",
          "contact_email": "jane@example.eu",
          "contact_phone": "415-1234567",
          "line_1": "417 Melrose Place",
          "line_2": "FLOOR 5",
          "postal_code": "90210",
          "city": "Los Angeles",
          "state": "CA",
          "country": "US"
        },
        "parcels": [
          {
            "length": 24,
            "width": 32,
            "height": 5,
            "weight": 0.5,
            "weight_unit":"kilograms",
            "quantity": 1,
            "is_dg":false
          }
        ],
        "customs_items": [
          {
            "description": "Shirts",
            "quantity": 2,
            "value": 20,
            "currency": "EUR",
            "weight": 500,
            "weight_unit":"grams",
            "hs_code": "123456789",
            "origin_country": "NL"
          }
        ],
        "incoterms": "DDU",
        "courier": "fedex_international_priority",
        "exclude_rates": true,
        "buy_label_synchronous": true
      }'

The above command returns JSON structured like this:

HTTP/1.1 201 Created
Content-Type:application/json;charset=UTF-8

{
  "shipment": {
    "created_at": "2021-08-27T09:46:58+00:00",
    "updated_at": "2021-08-27T09:47:05+00:00",
    "id": "SHIP0002181",
    "mode": "test",
    "platform_name": "AMAZON",
    "platform_order_number": "#1234",
    "reference": "shipment reference",
    "incoterms": "DDU",
    "status": "label_generated",
    "error_message": null,
    "origin_address": {
      "sender_id": "ecorp",
      "company_name": "E-Corp",
      "contact_name": "Elliot Alderson",
      "contact_email": "ealderson@ecorp.com",
      "contact_phone": "(212) 555-0179",
      "line_1": "Gustav Mahlerplein 53",
      "line_2": null,
      "postal_code": "1082 MA",
      "city": "Amsterdam",
      "state": null,
      "country": "NL",
      "country_full": "Netherlands",
      "eori_number": null,
      "vat_number": null
    },
    "destination_address": {
      "company_name": null,
      "contact_name": "Jane Doe",
      "contact_email": "jane@example.eu",
      "contact_phone": "415-1234567",
      "line_1": "417 Melrose Place",
      "line_2": "FLOOR 5",
      "postal_code": "90210",
      "city": "Los Angeles",
      "state": "CA",
      "country": "US",
      "country_full": "United States",
      "eori_number": null,
      "vat_number": null
    },
    "parcels": [
      {
        "id": "7a4a3c83-4e98-489e-a7ec-6d0861cebfd4",
        "box_name": "Custom Box",
        "tracking_number": "794658261734",
        "length": 24,
        "width": 32,
        "height": 5,
        "dimensions_unit": "cm",
        "weight": 0.5,
        "weight_unit": "kg",
        "quantity": 1,
        "is_custom": true,
        "is_dg": false
      }
    ],
    "customs_items": [
      {
        "id": "58503411-f9cc-419e-8cc1-0aa9e3cbc816",
        "sku": null,
        "description": "Shirts",
        "quantity": 2,
        "value": 20,
        "currency": "EUR",
        "weight": 500,
        "weight_unit": "grams",
        "hs_code": "123456789",
        "origin_country": "NL"
      }
    ],
    "selected_courier": {
      "carrier_id": "7605c1fc-683d-4860-a010-8fda26f2a79a",
      "carrier_admin_name": "fedex_international_priority",
      "carrier_display_name": "FedEx International Priority",
      "carrier_description": "A highly reliable, express, time-definite, customs-cleared, door-to-door service for your worldwide packages up to 68kg per unit.",
      "pickup_available": true,
      "min_delivery_time": 1,
      "max_delivery_time": 3
    },
    "label": {
      "date": "2021-08-27T11:47:05.000000Z",
      "file_type": "application\/pdf",
      "barcode": "794658261734",
      "url": "\/storage\/\/labels\/da470f08-20b3-4fa8-8464-724e4b8122c1.pdf",
      "epl2_url": null,
      "zpl_url": null,
      "pdf_url": "https:\/\/os-saas.test\/application\/labels\/da470f08-20b3-4fa8-8464-724e4b8122c1.pdf",
      "docs_url": "https:\/\/os-saas.test\/application\/docs\/da470f08-20b3-4fa8-8464-724e4b8122c1.pdf",
      "size": "4x6",
      "resolution": 200
    },
    "tracking_code": "794658261734"
  }
}

Before a shipment can be confirmed and a label can be purchased, a shipment needs to be created through this endpoint.

HTTP Request

POST https://app.omniship.eu/api/shipping/v1/shipments

Arguments

Attribute Type Description
platform_name string optional Sales platform name. Maximum: 200 characters
platform_order_number string optional Order number on the sales platform.
reference string optional Reference information that prints on the shipping label (if courier allows it).
sender_id string optional ID of the sender Address object. The origin address for the shipment is set by this ID. If the sender id is omitted the default sender address is set as origin address.
destination_address object optional Address object that should be used as receiver address.
parcels array required Array of Parcel objects with package details for the shipment to be sent.
customs_items array required Array of Customs Item objects with details of the products in the shipment for customs.
incoterms string optional The terms of sale of the Shipment. Valid values are DDP, DDU, DAP.
courier string optional Select a specific couriers admin_name to create the shipment with. Use the Couriers API resource to retrieve a list of available couriers and their admin names.
exclude_rates boolean optional When true rates will not be calculated for the shipment, which will lead to a faster response. Value is false by default.
buy_label boolean optional When true a shipment is created and the label is bought in a single API call instead of two. Value is false by default.
buy_label_synchronous boolean optional When true a label is generated synchronously and returned directly in the response. Value is false by default.

Address Object definitions:

Field Name
Type
Description

contact_name

string

required Address contact name. Maximum: 35 characters

company_name

string

optional Address company name. Maximum: 35 characters

contact_email

string

optional Address contact email address. Maximum: 50 characters

contact_phone

string

required Address contact phone number. Maximum: 18 characters

line_1

string

required Address line 1. Maximum: 35 characters

line_2

string

optional Address line 2. Maximum: 35 characters

postal_code

string

required if Country is postal aware. Address postal code.

city

string

required Address city

state

string

required if Country has states. (US, CA, MX, IN)

country

string

required Address country code in Alpha 2 Format (ISO 3166-1)

eori_number

string

optional Economic Operators Registration and Identification (EORI) number

vat_number

string

optional The consignee's tax identification number

Parcel definitions:

Field Name
Type
Description

box

string

optional Courier or Custom Box slug. Use the Boxes API Resource to retrieve a list of available boxes.

length

integer

optional The length of the parcel in cm

width

integer

optional The width of the parcel in cm

height

integer

optional The height of the parcel in cm

weight

float

required The weight of the parcel. By default the weight will be in kilograms, the weight can be set in grams by setting the weight_unit attribute

weight_unit

string

Optional The unit in which the weight is measured. Valid values are: kilograms, grams. Default is kilograms

quantity

integer

optional The quantity of parcels with the same measures. Default is 1

CustomsItem definitions:

Field Name
Type
Description

sku

string

optional Product sku. Use the Product API Resource to retrieve a list of available products.

description

string

required if sku is not given or null. Description of the item being shipped

quantity

integer

optional Quantity of the item to be shipped, must be greater than zero. Defaults to 1

value

object

required if sku is not given or null. Value of a single item

currency

string

Optional The currency of the item value. The account's default currency will be used if not specified

weight

object

required if sku is not given or null. The weight of the item

hs_code

string

Optional Harmonized Tariff Code

origin_country

string

required if sku is not given or null. Origin country of the item in Alpha 2 format.

Update a Shipment

curl "https://app.omniship.eu/api/shipping/v1/shipments/SHIP0002184"
  -X PATCH
  -H "Authorization: Bearer FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"
  -d '{
        "destination_address": {
          "contact_name": "Elliot Alderson"
        },
        "incoterms": "DAP",
        "exclude_rates": false
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8

{
  "shipment": {
    "created_at": "2021-08-27T13:45:16+00:00",
    "updated_at": "2021-08-27T13:45:38+00:00",
    "id": "SHIP0002184",
    "mode": "test",
    "platform_name": "AMAZON",
    "platform_order_number": "#1234",
    "reference": "shipment reference",
    "incoterms": "DAP",
    "status": "ready_to_process",
    "error_message": null,
    "origin_address": {
      "sender_id": "ecorp",
      "company_name": "E-Corp",
      "contact_name": "Elliot Alderson",
      "contact_email": "ealderson@ecorp.com",
      "contact_phone": "(212) 555-0179",
      "line_1": "Gustav Mahlerplein 53",
      "line_2": null,
      "postal_code": "1082 MA",
      "city": "Amsterdam",
      "state": null,
      "country": "NL",
      "country_full": "Netherlands",
      "eori_number": null,
      "vat_number": null
    },
    "destination_address": {
      "company_name": null,
      "contact_name": "Elliot Alderson",
      "contact_email": "jane@example.eu",
      "contact_phone": "415-1234567",
      "line_1": "417 Melrose Place",
      "line_2": "FLOOR 5",
      "postal_code": "90210",
      "city": "Los Angeles",
      "state": "CA",
      "country": "US",
      "country_full": "United States",
      "eori_number": null,
      "vat_number": null
    },
    "parcels": [
      {
        "id": "11b322a5-5242-4cd3-bd7d-3edc6d2332a0",
        "box_name": "Custom Box",
        "tracking_number": null,
        "length": 24,
        "width": 32,
        "height": 5,
        "dimensions_unit": "cm",
        "weight": 0.5,
        "weight_unit": "kg",
        "quantity": 1,
        "is_custom": true
      }
    ],
    "customs_items": [
      {
        "id": "1b7fca7a-1118-4ce4-baf7-13f85697ef07",
        "sku": null,
        "description": "Shirts",
        "quantity": 2,
        "value": 20,
        "currency": "EUR",
        "weight": 500,
        "weight_unit": "grams",
        "hs_code": "123456789",
        "origin_country": "NL"
      }
    ],
    "rates": [
      {
        "carrier_id": "7605c1fc-683d-4860-a010-8fda26f2a79a",
        "carrier_admin_name": "fedex_international_priority",
        "carrier_display_name": "FedEx International Priority",
        "carrier_description": "A highly reliable, express, time-definite, customs-cleared, door-to-door service for your worldwide packages up to 68kg per unit.",
        "pickup_available": true,
        "min_delivery_time": 1,
        "max_delivery_time": 3,
        "shipment_charge": 22.91,
        "fuel_surcharge": 3.64,
        "currency": "EUR"
      },
      {
        "carrier_id": "56ea6a76-26a8-4d4e-a649-fadff28d1832",
        "carrier_admin_name": "fedex_international_economy",
        "carrier_display_name": "FedEx International Economy",
        "carrier_description": "A cost-saving solution for your less time-sensitive deliveries. A reliable, door-to-door, Customs-cleared, service between Europe, the Middle East and the US.",
        "pickup_available": true,
        "min_delivery_time": 2,
        "max_delivery_time": 6,
        "shipment_charge": 23.07,
        "fuel_surcharge": 3.66,
        "currency": "EUR"
      }
    ],
    "selected_courier": {
      "carrier_id": "7605c1fc-683d-4860-a010-8fda26f2a79a",
      "carrier_admin_name": "fedex_international_priority",
      "carrier_display_name": "FedEx International Priority",
      "carrier_description": "A highly reliable, express, time-definite, customs-cleared, door-to-door service for your worldwide packages up to 68kg per unit.",
      "pickup_available": true,
      "min_delivery_time": 1,
      "max_delivery_time": 3,
      "shipment_charge": 22.91,
      "fuel_surcharge": 3.64,
      "currency": "EUR"
    },
    "label": null,
    "tracking_code": null
  }
}

This endpoint updates a new Shipment in OMNISHIP. A shipment can only be updated if a label is not bought.

HTTP Request

PATCH https://app.omniship.eu/api/shipping/v1/shipments/<ID>

URL Parameters

Parameter Description
ID The Shipment ID of the Shipment to update

Arguments

Attribute Type Description
platform_name string Sales platform name. Maximum: 200 characters
platform_order_number string Order number on the sales platform.
reference string Reference information that prints on the shipping label (if courier allows it).
sender_id string ID of the sender Address object. The origin address for the shipment is set by this ID. If the sender id is omitted the default sender address is set as origin address.
destination_address object Address object that should be used as receiver address.
parcels array Array of Parcel objects with package details for the shipment to be sent.
customs_items array Array of Customs Item objects with details of the products in the shipment for customs.
incoterms string The terms of sale of the Shipment. Valid values are DDP, DDU, DAP.
courier string Select a specific courier to create the shipment with.
exclude_rates boolean When true rates will not be calculated for the shipment, which will lead to a faster response. Value is false by default.

Address Object definitions:

Field Name
Type
Description

contact_name

string

Address contact name. Maximum: 35 characters

company_name

string

Address company name. Maximum: 35 characters

contact_email

string

Address contact email address. Maximum: 50 characters

contact_phone

string

Address contact phone number. Maximum: 18 characters

line_1

string

Address line 1. Maximum: 35 characters

line_2

string

Address line 2. Maximum: 35 characters

postal_code

string

required if Country is postal aware. Address postal code.

city

string

Address city

state

string

required if Country has states. (US, CA, MX, IN)

country

string

Address country code in Alpha 2 Format (ISO 3166-1)

eori_number

string

Economic Operators Registration and Identification (EORI) number

vat_number

string

The consignee's tax identification number

Parcel definitions:

Field Name
Type
Description

id

string

required when updating an existing Parcel object. Id of the object updating.

box

string

required when adding a new Parcel object to the shipment. Courier or Custom Box slug. Use the Boxes API Resource to retrieve a list of available boxes.

length

integer

optional The length of the parcel in cm

width

integer

optional The width of the parcel in cm

height

integer

optional The height of the parcel in cm

weight

float

required_when adding a new Parcel object to the shipment. By default the weight will be in kilograms, the weight can be set in grams by setting the weight_unit attribute

weight_unit

string

Optional The unit in which the weight is measured. Valid values are: kilograms, grams. Default is kilograms

quantity

integer

optional The quantity of parcels with the same measures. Default is 1

CustomsItem definitions:

Field Name
Type
Description

id

string

required when updating an existing Customs Item object. Id of the object updating.

sku

string

optional Product sku. Use the Product API Resource to retrieve a list of available products.

description

string

required when adding a new Custom Item object to the shipment and a sku is not given or null. Description of the item being shipped

quantity

integer

optional Quantity of the item to be shipped, must be greater than zero. Defaults to 1

value

object

required when adding a new Custom Item object to the shipment and a sku is not given or null. Value of a single item

currency

string

Optional The currency of the item value. The account's default currency will be used if not specified

weight

object

required when adding a new Custom Item object to the shipment and a sku is not given or null. The weight of the item

hs_code

string

Optional Harmonized Tariff Code

origin_country

string

required when adding a new Custom Item object to the shipment and a sku is not given or null. Origin country of the item in Alpha 2 format.

Get a Shipment

curl "https://app.omniship.eu/api/shipping/v1/shipments/SHIP0002184"
  -H "Authorization: Bearer FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8

{
  "shipment": {
    "created_at": "2021-08-27T13:45:16+00:00",
    "updated_at": "2021-08-27T13:45:38+00:00",
    "id": "SHIP0002184",
    "mode": "test",
    "platform_name": "AMAZON",
    "platform_order_number": "#1234",
    "reference": "shipment reference",
    "incoterms": "DAP",
    "status": "ready_to_process",
    "error_message": null,
    "origin_address": {
      "sender_id": "ecorp",
      "company_name": "E-Corp",
      "contact_name": "Elliot Alderson",
      "contact_email": "ealderson@ecorp.com",
      "contact_phone": "(212) 555-0179",
      "line_1": "Gustav Mahlerplein 53",
      "line_2": null,
      "postal_code": "1082 MA",
      "city": "Amsterdam",
      "state": null,
      "country": "NL",
      "country_full": "Netherlands",
      "eori_number": null,
      "vat_number": null
    },
    "destination_address": {
      "company_name": null,
      "contact_name": "Elliot Alderson",
      "contact_email": "jane@example.eu",
      "contact_phone": "415-1234567",
      "line_1": "417 Melrose Place",
      "line_2": "FLOOR 5",
      "postal_code": "90210",
      "city": "Los Angeles",
      "state": "CA",
      "country": "US",
      "country_full": "United States",
      "eori_number": null,
      "vat_number": null
    },
    "parcels": [
      {
        "id": "11b322a5-5242-4cd3-bd7d-3edc6d2332a0",
        "box_name": "Custom Box",
        "tracking_number": null,
        "length": 24,
        "width": 32,
        "height": 5,
        "dimensions_unit": "cm",
        "weight": 0.5,
        "weight_unit": "kg",
        "quantity": 1,
        "is_custom": true
      }
    ],
    "customs_items": [
      {
        "id": "1b7fca7a-1118-4ce4-baf7-13f85697ef07",
        "sku": null,
        "description": "Shirts",
        "quantity": 2,
        "value": 20,
        "currency": "EUR",
        "weight": 500,
        "weight_unit": "grams",
        "hs_code": "123456789",
        "origin_country": "NL"
      }
    ],
    "rates": [
      {
        "carrier_id": "7605c1fc-683d-4860-a010-8fda26f2a79a",
        "carrier_admin_name": "fedex_international_priority",
        "carrier_display_name": "FedEx International Priority",
        "carrier_description": "A highly reliable, express, time-definite, customs-cleared, door-to-door service for your worldwide packages up to 68kg per unit.",
        "pickup_available": true,
        "min_delivery_time": 1,
        "max_delivery_time": 3,
        "shipment_charge": 22.91,
        "fuel_surcharge": 3.64,
        "currency": "EUR"
      },
      {
        "carrier_id": "56ea6a76-26a8-4d4e-a649-fadff28d1832",
        "carrier_admin_name": "fedex_international_economy",
        "carrier_display_name": "FedEx International Economy",
        "carrier_description": "A cost-saving solution for your less time-sensitive deliveries. A reliable, door-to-door, Customs-cleared, service between Europe, the Middle East and the US.",
        "pickup_available": true,
        "min_delivery_time": 2,
        "max_delivery_time": 6,
        "shipment_charge": 23.07,
        "fuel_surcharge": 3.66,
        "currency": "EUR"
      }
    ],
    "selected_courier": {
      "carrier_id": "7605c1fc-683d-4860-a010-8fda26f2a79a",
      "carrier_admin_name": "fedex_international_priority",
      "carrier_display_name": "FedEx International Priority",
      "carrier_description": "A highly reliable, express, time-definite, customs-cleared, door-to-door service for your worldwide packages up to 68kg per unit.",
      "pickup_available": true,
      "min_delivery_time": 1,
      "max_delivery_time": 3,
      "shipment_charge": 22.91,
      "fuel_surcharge": 3.64,
      "currency": "EUR"
    },
    "label": null,
    "tracking_code": null
  }
}

This endpoint retrieves a specific Shipment.

HTTP Request

GET https://app.omniship.eu/api/shipping/v1/shipments/<ID>

URL Parameters

Parameter Description
ID The Shipment ID of the Shipment

List all Shipments

curl "https://app.omniship.eu/api/shipping/v1/shipments"
  -H "Authorization: Bearer FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8

{
    "shipments": [
    {
      "created_at": "2021-08-27T13:45:16+00:00",
      "updated_at": "2021-08-27T13:47:44+00:00",
      "id": "SHIP0002184",
      "mode": "test",
      "platform_name": "AMAZON",
      "platform_order_number": "#1234",
      "reference": "shipment reference",
      "incoterms": "DAP",
      "status": "ready_to_process",
      "error_message": null,
      "origin_address": {
        "sender_id": "ecorp",
        "company_name": "E-Corp",
        "contact_name": "Elliot Alderson",
        "contact_email": "ealderson@ecorp.com",
        "contact_phone": "(212) 555-0179",
        "line_1": "Gustav Mahlerplein 53",
        "line_2": null,
        "postal_code": "1082 MA",
        "city": "Amsterdam",
        "state": null,
        "country": "NL",
        "country_full": "Netherlands",
        "eori_number": null,
        "vat_number": null
      },
      "destination_address": {
        "company_name": null,
        "contact_name": "Elliot Alderson",
        "contact_email": "jane@example.eu",
        "contact_phone": "415-1234567",
        "line_1": "417 Melrose Place",
        "line_2": "FLOOR 5",
        "postal_code": "90210",
        "city": "Los Angeles",
        "state": "CA",
        "country": "US",
        "country_full": "United States",
        "eori_number": null,
        "vat_number": null
      },
      "parcels": [
        {
          "id": "11b322a5-5242-4cd3-bd7d-3edc6d2332a0",
          "box_name": "Custom Box",
          "tracking_number": null,
          "length": 24,
          "width": 32,
          "height": 5,
          "dimensions_unit": "cm",
          "weight": 0.5,
          "weight_unit": "kg",
          "quantity": 1,
          "is_custom": true
        }
      ],
      "customs_items": [
        {
          "id": "1b7fca7a-1118-4ce4-baf7-13f85697ef07",
          "sku": null,
          "description": "Shirts",
          "quantity": 2,
          "value": 20,
          "currency": "EUR",
          "weight": 500,
          "weight_unit": "grams",
          "hs_code": "123456789",
          "origin_country": "NL"
        }
      ],
      "rates": [
        {
          "carrier_id": "56ea6a76-26a8-4d4e-a649-fadff28d1832",
          "carrier_admin_name": "fedex_international_economy",
          "carrier_display_name": "FedEx International Economy",
          "carrier_description": "A cost-saving solution for your less time-sensitive deliveries. A reliable, door-to-door, Customs-cleared, service between Europe, the Middle East and the US.",
          "pickup_available": true,
          "min_delivery_time": 2,
          "max_delivery_time": 6,
          "shipment_charge": 23.07,
          "fuel_surcharge": 3.66,
          "currency": "EUR"
        },
        {
          "carrier_id": "7605c1fc-683d-4860-a010-8fda26f2a79a",
          "carrier_admin_name": "fedex_international_priority",
          "carrier_display_name": "FedEx International Priority",
          "carrier_description": "A highly reliable, express, time-definite, customs-cleared, door-to-door service for your worldwide packages up to 68kg per unit.",
          "pickup_available": true,
          "min_delivery_time": 1,
          "max_delivery_time": 3,
          "shipment_charge": 22.91,
          "fuel_surcharge": 3.64,
          "currency": "EUR"
        }
      ],
      "selected_courier": {
        "carrier_id": "7605c1fc-683d-4860-a010-8fda26f2a79a",
        "carrier_admin_name": "fedex_international_priority",
        "carrier_display_name": "FedEx International Priority",
        "carrier_description": "A highly reliable, express, time-definite, customs-cleared, door-to-door service for your worldwide packages up to 68kg per unit.",
        "pickup_available": true,
        "min_delivery_time": 1,
        "max_delivery_time": 3,
        "shipment_charge": 22.91,
        "fuel_surcharge": 3.64,
        "currency": "EUR"
      },
      "label": null,
      "tracking_code": null
    },
    {
      "created_at": "2021-08-27T12:25:40+00:00",
      "updated_at": "2021-08-27T12:25:41+00:00",
      "id": "SHIP0002183",
      "mode": "test",
      "platform_name": "AMAZON",
      "platform_order_number": "#1234",
      "reference": "shipment reference",
      "incoterms": "DDU",
      "status": "ready_to_process",
      "error_message": null,
      "origin_address": {
        "sender_id": "ecorp",
        "company_name": "E-Corp",
        "contact_name": "Elliot Alderson",
        "contact_email": "ealderson@ecorp.com",
        "contact_phone": "(212) 555-0179",
        "line_1": "Gustav Mahlerplein 53",
        "line_2": null,
        "postal_code": "1082 MA",
        "city": "Amsterdam",
        "state": null,
        "country": "NL",
        "country_full": "Netherlands",
        "eori_number": null,
        "vat_number": null
      },
      "destination_address": {
        "company_name": null,
        "contact_name": "Jane Doe",
        "contact_email": "jane@example.eu",
        "contact_phone": "415-1234567",
        "line_1": "417 Melrose Place",
        "line_2": "FLOOR 5",
        "postal_code": "90210",
        "city": "Los Angeles",
        "state": "CA",
        "country": "US",
        "country_full": "United States",
        "eori_number": null,
        "vat_number": null
      },
      "parcels": [
        {
          "id": "c1146de9-852d-4b32-a6a3-899e21a5818c",
          "box_name": "Custom Box",
          "tracking_number": null,
          "length": 24,
          "width": 32,
          "height": 5,
          "dimensions_unit": "cm",
          "weight": 0.5,
          "weight_unit": "kg",
          "quantity": 1,
          "is_custom": true
        }
      ],
      "customs_items": [
        {
          "id": "1455c5ad-98ec-4157-8248-9a8e0d0dbc58",
          "sku": "test",
          "description": "test",
          "quantity": 1,
          "value": 20,
          "currency": "EUR",
          "weight": 200,
          "weight_unit": "grams",
          "hs_code": "234234234",
          "origin_country": "NL"
        }
      ],
      "selected_courier": {
        "carrier_id": "7605c1fc-683d-4860-a010-8fda26f2a79a",
        "carrier_admin_name": "fedex_international_priority",
        "carrier_display_name": "FedEx International Priority",
        "carrier_description": "A highly reliable, express, time-definite, customs-cleared, door-to-door service for your worldwide packages up to 68kg per unit.",
        "pickup_available": true,
        "min_delivery_time": 1,
        "max_delivery_time": 3
      },
      "label": null,
      "tracking_code": null
    },
    {},
    {}
    ]
}

This endpoint retrieves all Shipments.

HTTP Request

GET https://app.omniship.eu/api/shipping/v1/shipments

Query params Type Description
shipment_id string Shipment ID provided when creating the shipment. If multiple, separate with a comma.
platform_order_number string Order number of the sales platform
created_at_from date Search for shipments created since this date
created_at_till date Search for shipments created since this date
label_state string Search by current label status of shipment. valid options: ready_to_process, processing, label_generated, error
page integer Which page number want to fetch, default: 1
per_page integer Number of Shipments per page to fetch, default: 25, max: 100

Delete a Shipment

curl "https://app.omniship.eu/api/shipping/v1/shipments/SHIP0002184"
  -X DELETE
  -H "Authorization: Bearer FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"

The above command returns JSON structured like this:

HTTP/1.1 204 No Content
Content-Type:application/json;charset=UTF-8

A shipment can be deleted through this endpoint. If the carrier allows it the shipment is also canceled in the carrier system. If the shipment is already canceled in the carrier system, the shipment is deleted in the OmniShip system

HTTP Request

DELETE https://app.omniship.eu/api/shipping/v1/shipments/<ID>

URL Parameters

Parameter Description
ID The Shipment ID of the Shipment to delete

Labels

With the Label resource, you can confirm a Shipment that was created using the Shipment API. Calling Buy Labels will confirm a Shipment with the selected Courier and begin generating the Label & Shipping Documents after checking your account’s balance is sufficient.

If your Shipment does not have a Courier assigned to it yet, you can specify a courier_id to the Label resource to choose your Courier and confirm your Shipment. If there is no assigned Courier and you don’t include a courier_id, we will assign the best value for money Courier to your Shipment.

Confirm and buy Labels

curl "https://app.omniship.eu/api/shipping/v1/labels"
  -X POST
  -H "Authorization: Bearer FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"
  -d '{
        "shipments": [
          {
            "shipment_id": "SHIP0002167"
          }
        ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 201 Created
Content-Type:application/json;charset=UTF-8

{
  "labels": {
    "message": "Your labels are being generated",
    "total_costs": 12.26,
    "labels": [
      {
        "shipment_id": "SHIP0002167",
        "platform_order_number": "#1234",
        "status": "processing",
        "label_url": null,
        "tracking_number": null
      }
    ]
  }
}

HTTP Request

POST https://app.omniship.eu/api/shipping/v1/rates

Arguments

Attribute Type Description
shipments array required Array of shipment id's where labels should be created for.
courier string optional Courier for which the label should be retrieved.

Trackings

The Tracking resource is used to list tracking information of previously created Shipments.

List all Trackings

curl "https://app.omniship.eu/api/shipping/v1/tracking"
  -H "Authorization: Bearer FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8

{
  "trackers": [
    {
      "updated_at": "2022-08-03T12:41:22.000000Z",
      "shipment_id": "SHIP0116354",
      "platform_order_number": "SHIP0116354",
      "tracking_code": "3SKABE076200888",
      "status": "delivered",
      "latest_event": "Shipment delivered,2022-08-03 12:51:40",
      "tracking_url": "https:\/\/www.internationalparceltracking.com\/Main.aspx#\/track\/3SKABE076200888\/NL\/5652 AG",
      "tracking_details": [
        {
          "checkpoint_date": "2022-08-03 12:51:40",
          "tracking_detail": "Shipment delivered",
          "location": null,
          "status": "delivered",
          "sub_status": "delivered001"
        },
        {
          "checkpoint_date": "2022-08-03 10:14:41",
          "tracking_detail": "Driver is en route",
          "location": null,
          "status": "in transit",
          "sub_status": "transit001"
        },
        {
          "checkpoint_date": "2022-08-03 10:00:26",
          "tracking_detail": "Shipment has been sorted",
          "location": null,
          "status": "in transit",
          "sub_status": "transit001"
        },
        {
          "checkpoint_date": "2022-08-03 00:47:56",
          "tracking_detail": "Shipment received by PostNL",
          "location": null,
          "status": "in transit",
          "sub_status": "transit001"
        },
        {
          "checkpoint_date": "2022-08-02 22:18:30",
          "tracking_detail": "Shipment expected, but not yet arrived at PostNL",
          "location": null,
          "status": "in transit",
          "sub_status": "transit001"
        }
      ]
    },
    {},
    {}
  ]
}

This endpoint retrieves all Trackers. Shipment Tracking Statuses

There are seven kinds of statuses been defined by OmniShip during the shipment transportation process, they are "Not Found", "Transit", "Out for Delivery", "Delivered", "Failed Attempt", "Exception" and "Expired". Those statuses are all judged by our system automatically according to the tracking details and are references to worldwide users.

HTTP Request

GET https://app.omniship.eu/api/shipping/v1/tracker

Query params Type Description
shipment_id string Shipment ID provided when creating the shipment. If multiple, separate with a comma.
platform_order_number string Order number of the sales platform
created_at_from date Search for trackers created since this date
created_at_till date Search for trackers created since this date
page integer Which page number want to fetch, default: 1
per_page integer Number of Shipments per page to fetch, default: 25, max: 100

Pickups

The Pickup resource is used to create, list, update and delete Pickups.

With the Pickup API, you can decide to ask the courier to pickup your shipments or drop off by yourself to the courier nearby.

Before you start to request a pickup, you have the option to retrieve available pickup options and then use the Request Pickup resource to ask the courier to collect your shipments in your preferred time slot.

Request a Pickup

curl "https://app.omniship.eu/api/shipping/v1/pickups"
  -X POST
  -H "Authorization: Bearer FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"
  -d '{
        "courier": "fedex_international_priority",
        "preferred_date": "2021-08-26",
        "preferred_max_time": "18:30",
        "preferred_min_time": "13:00",
        "shipment_ids": [
          "SHIP0002166"
        ]
      }'

The above command returns JSON structured like this:

HTTP/1.1 201 Created
Content-Type:application/json;charset=UTF-8

{
  "courier_name": "FedEx",
  "shipments": [
    [
      "SHIP0002166"
    ]
  ],
  "pickup": {
    "pickup_id": "PU0000001",
    "pickup_reference_number": "QNQA287",
    "preferred_min_time": "2021-08-26T13:00:00+00:00",
    "preferred_max_time": "2021-08-26T18:30:00+00:00",
    "pickup_fee": 0,
    "shipments_count": 1,
    "total_weight": 2,
    "status": "pending",
    "picked_up_timestamp": "2021-08-25T14:00:00+00:00",
    "address": {
      "company_name": null,
      "contact_name": "Fred Tuijnman",
      "contact_email": "ftuijnman@nicoud.nl",
      "contact_phone": "+31-(0)72 567 1000",
      "line_1": "Newtonstraat 46",
      "line_2": null,
      "postal_code": "1704 SB",
      "city": "Heerhugowaard",
      "state": null,
      "country": "NL",
      "country_full": "Netherlands",
      "eori_number": null,
      "vat_number": null
    }
  }
}

HTTP Request

POST https://app.omniship.eu/api/shipping/v1/pickups

Arguments

Attribute Type Description
courier_name string required Courier admin name. Use the Courier API to retrieve a list of available couriers.
preferred_date date optional Date when the shipment(s) should be picked up. By default the current date is selected. Format: yyyy-mm-dd
preferred_max_time time required Latest pickup time. Format: hh:mm.
preferred_min_time time required Preferred time when shipment(s) ready for pickup. Format: hh:mm.
shipment_ids array required Array of shipment_ids for which the pickup is requested.

Mark a PickUp as picked_up

curl "https://app.omniship.eu/api/shipping/v1/pickups/PU0000001"
  -X PATCH
  -H "Authorization: Bearer FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"
  -d '{
        "picked_up_timestamp": "2021-08-25T14:00"
      }'

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8

{
  "pickup": {
    "pickup_id": "PU0000001",
    "pickup_reference_number": "QNQA287",
    "preferred_min_time": "2021-08-26T13:00:00+00:00",
    "preferred_max_time": "2021-08-26T18:30:00+00:00",
    "pickup_fee": 0,
    "shipments_count": 1,
    "total_weight": 2,
    "status": "picked_up",
    "picked_up_timestamp": "2021-08-25T14:00:00+00:00",
    "address": {
      "company_name": null,
      "contact_name": "Fred Tuijnman",
      "contact_email": "ftuijnman@nicoud.nl",
      "contact_phone": "+31-(0)72 567 1000",
      "line_1": "Newtonstraat 46",
      "line_2": null,
      "postal_code": "1704 SB",
      "city": "Heerhugowaard",
      "state": null,
      "country": "NL",
      "country_full": "Netherlands",
      "eori_number": null,
      "vat_number": null
    }
  }
}

This endpoint manually sets the state of PickUp in OMNISHIP to picked_up.

HTTP Request

PATCH https://app.omniship.eu/api/shipping/v1/shipments/<ID>

URL Parameters

Parameter Description
ID The PickUp ID of the PickUp to mark as picked up

Arguments

Attribute Type Description
picked_up_timestamp date Timestamp of the pickup of the shipment(s). Format: yyyy-mm-ddThh:mm.

Get a PickUp

curl "https://app.omniship.eu/api/shipping/v1/pickups/PU0000001"
  -H "Authorization: Bearer FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8

{
  "pickup": {
    "pickup_id": "PU0000001",
    "pickup_reference_number": "QNQA287",
    "preferred_min_time": "2021-08-26T13:00:00+00:00",
    "preferred_max_time": "2021-08-26T18:30:00+00:00",
    "pickup_fee": 0,
    "shipments_count": 1,
    "total_weight": 2,
    "status": "picked_up",
    "picked_up_timestamp": "2021-08-25T14:00:00+00:00",
    "address": {
      "company_name": null,
      "contact_name": "Fred Tuijnman",
      "contact_email": "ftuijnman@nicoud.nl",
      "contact_phone": "+31-(0)72 567 1000",
      "line_1": "Newtonstraat 46",
      "line_2": null,
      "postal_code": "1704 SB",
      "city": "Heerhugowaard",
      "state": null,
      "country": "NL",
      "country_full": "Netherlands",
      "eori_number": null,
      "vat_number": null
    }
  }
}

This endpoint retrieves a specific PickUp.

HTTP Request

GET https://app.omniship.eu/api/shipping/v1/pickups/<ID>

URL Parameters

Parameter Description
ID The Pickup ID of the PickUp

List all PickUps

curl "https://app.omniship.eu/api/shipping/v1/pickups"
  -H "Authorization: Bearer FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8

{
    "pickups": [
    {
      "pickup_id": "PU0000001",
      "pickup_reference_number": "QNQA287",
      "preferred_min_time": "2021-08-26T13:00:00+00:00",
      "preferred_max_time": "2021-08-26T18:30:00+00:00",
      "pickup_fee": 0,
      "shipments_count": 1,
      "total_weight": 2,
      "status": "picked_up",
      "picked_up_timestamp": "2021-08-25T14:00:00+00:00",
      "address": {
        "company_name": null,
        "contact_name": "Fred Tuijnman",
        "contact_email": "ftuijnman@nicoud.nl",
        "contact_phone": "+31-(0)72 567 1000",
        "line_1": "Newtonstraat 46",
        "line_2": null,
        "postal_code": "1704 SB",
        "city": "Heerhugowaard",
        "state": null,
        "country": "NL",
        "country_full": "Netherlands",
        "eori_number": null,
        "vat_number": null
    },
    {"..."},
    {"..."}
    ]
}

This endpoint retrieves all PickUps.

HTTP Request

GET https://app.omniship.eu/api/shipping/v1/shipments

Query params Type Description
pickup_id string PickUp ID provided when creating the pickup. If multiple, separate with a comma.
pickup_reference_number string Reference number of the pickup
status string Search by current status of the pickup. valid options: pending, picked_up, canceled
page integer Which page number want to fetch, default: 1
per_page integer Number of Pickups per page to fetch, default: 25, max: 100

Cancel a Pickup

curl "https://app.omniship.eu/api/shipping/v1/pickups/PU0000001"
  -X DELETE
  -H "Authorization: Bearer FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"

The above command returns JSON structured like this:

HTTP/1.1 204 No Content
Content-Type:application/json;charset=UTF-8

HTTP Request

DELETE https://app.omniship.eu/api/shipping/v1/pickups/<ID>

URL Parameters

Parameter Description
ID The Pickup ID of the PickUp to cancel

Boxes

The Boxes API allows you to retrieve a list of available courier boxes and your own boxes.

List all Boxes

curl "https://app.omniship.eu/api/shipping/v1/boxes"
  -H "Authorization: Bearer FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8

{
    "boxes": [
    {
      "courier_name": null,
      "name": "test",
      "slug": "test",
      "length": 10,
      "width": 10,
      "height": 10,
      "weight": 0,
      "max_weight": null,
      "is_custom": true
    },
    {
      "courier_name": "FedEx",
      "name": "FedEx Tube",
      "slug": "fedex-tube",
      "length": 97,
      "width": 15,
      "height": 15,
      "weight": 9,
      "max_weight": null,
      "is_custom": false
    },
    {
      "courier_name": "FedEx",
      "name": "FedEx Envelope",
      "slug": "fedex-envelope",
      "length": 24,
      "width": 32,
      "height": 1,
      "weight": 0.5,
      "max_weight": 500,
      "is_custom": false
    },
    {"..."},
    {"..."}
    ]
}

HTTP Request

GET https://app.omniship.eu/api/shipping/v1/boxes

Couriers

The Couriers API allows you to retrieve a list of available couriers.

List all Couriers

curl "https://app.omniship.eu/api/shipping/v1/couriers"
  -H "Authorization: Bearer FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8

{
    "couriers": [
    {
      "courier_name": "FedEx",
      "admin_name": "fedex_international_economy",
      "service_name": "FedEx International Economy",
      "pickup_available": true,
      "transit_from": 2,
      "transit_till": 6,
      "max_weight": 68
    },
    {
      "courier_name": "FedEx",
      "admin_name": "fedex_international_priority",
      "service_name": "FedEx International Priority",
      "pickup_available": true,
      "transit_from": 1,
      "transit_till": 3,
      "max_weight": 68
    },
    {
      "courier_name": "FedEx",
      "admin_name": "fedex_priority_overnight",
      "service_name": "FedEx Priority Overnight",
      "pickup_available": true,
      "transit_from": 1,
      "transit_till": 1,
      "max_weight": 68
    },
    {"..."},
    {"..."}
    ]
}

HTTP Request

GET https://app.omniship.eu/api/shipping/v1/couriers

Errors

The Cross Border API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The resource requested is hidden or for administrators only.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The resource requested has been removed from our servers.
429 Too Many Requests -- You're requesting too many resources.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
shell