Shipsgo
API docs by Redocly

Shipsgo API (2.0.0)

Contact Us: support@shipsgo.com Terms of Service

The Shipsgo API is built on REST principles. Authenticated users can interact with any of our URIs by using the specified HTTP request method. Our API has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

All requests to Shipsgo API require you to authenticate yourself to the service. In order to do this you must send X-Shipsgo-User-Token header with the correct API token. If you don't have an API token, you can create one from "Shipsgo API" section on your dashboard.

If you use Shipsgo with multiple users (sub-accounts), API tokens are associated with a single user. Each account has different permission on API endpoints based on their role, similar to dashboard.

Role Description
Full Access View & manage (delete/update) all shipments of the company.
Co-Worker View & manage (delete/update) shipments only created by itself.
Co-Worker Plus View all shipments of the company, manage (delete/update) shipments only created by itself.

If you want to check permissions of your users you can view/manage from "Sub Accounts" section on your dashboard.

HTTP response codes

Shipsgo uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with Shipsgo's servers (these are rare).

Code Description Reason
200 Success Everything went smooth.
401 Unauthorized Missing or invalid authentication token.
402 Payment Required Not enough credits.
403 Forbidden User not authorized to perform the operation.
404 Not Found Requested resource is not found.
409 Conflict The requested resource already exists.
422 Unprocessable Content Something with the payload isn't quite right, this could be malformed JSON or incorrect fields.
429 Too Many Requests Client has sent too many requests in a given amount of time.
500 Internal Server Error The server encountered an unexpected condition.
503 Service Unavailable The server is down for maintenance. This is a temporary state.

Rate Limits

The Shipsgo API uses a number of safeguards against bursts of incoming traffic to help maximize its stability. For your company, the API rate limit is 100 requests per minute. This limit applies collectively across all users within the company. You can use the headers that are sent with each response to determine the current status of your rate limit. If you send many requests in a short window, you might see error responses with status code 429.

Header Description
X-RateLimit-Limit The maximum number of requests that you can make per minute.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets, in UTC epoch seconds.

List Endpoints

All top-level API resources have support for bulk fetches. These list endpoints share a common structure for filtering, sorting and pagination. For example, you can list your air shipments with upcoming arrivals in order:

[GET] /air/shipments?filters[status]=eq:EN_ROUTE&order_by=date_of_rcf,asc

There are a variety of different filters that can be used to each list enpoint. Filters can be used together in different combinations. When multiple filters are applied, they will be combined using the AND condition. Common structure is filters[field]=operator:value(s). Each field has corresponding operators. You can find the field & operator mappings in the filters section of the relevant endpoint. The following operators are supported:

Operator Description
eq Equal to a specific value.
not_eq Not equal to a specific value.
contains Checks if the field value contains a specific substring.
not_contains Checks if the field value does not contain a specific substring.
in Checks if the field value is within a list of values (, separated).
not_in Checks if the field value is not within a list of values (, separated).
with Checks if the field value is within a list of values (, separated).
without Checks if the field value is not within a list of values (, separated).
gt Greater than a specific value.
gte Greater than or equal to a specific value.
lt Less than a specific value.
lte Less than or equal to a specific value.
between Checks if the field value is between two values (... separated).

You can sort the list with order_by parameter. Common structure is order_by=field,direction. You can find the available field list in the order_by section of the relevant endpoint and direction can be asc (ascending) or desc (descending). If you omit the direction, the default sort direction is asc (ascending).

For the pagination you can use skip & take parameters with non-negative integer values.

AIR - Airlines

This section provides a comprehensive set of endpoints for airlines.

AIR - List of airlines

The shipments list endpoint allows you to retrieve a list of airlines. This includes options to apply various filters and sorting.

Example #1: To filter the trackable airlines.

/air/airlines?filters[status]=eq:ACTIVE

Example #2: To filter airlines that contain ARABIA in their name.

/air/airlines?filters[name]=contains:ARABIA
Authorizations:
Shipsgo User Token
query Parameters
object <Dictionary<string, string>>

You can use the following filters with their respective operators. Common structure is filters[field]=operator:value(s).

Field Operators Description
iata eq The IATA code of the airline. Ex: TK, QR, AF, LH
name eq, contains, not_contains The name of the airline.
status eq Enum: ACTIVE, PASSIVE
prefixes with, without The air waybill(AWB) prefix(es) for airline(s). Ex: 235, 176
order_by
string

You can sort the list with following fields. Common structure is order_by=field,direction.

Field Description
iata The IATA code of the airline.
name The name of the airline.

Note: By default the results are ordered by the name in asc (ascending) order.

skip
integer >= 0

The number of records to skip before returning the results. The default value is 0.

take
integer [ 1 .. 100 ]

The number of records to return. The default value is 25.

Responses

Response Schema: application/json
message
string

A message indicating the result (SUCCESS).

Array of objects

List of shipments.

Array
iata
string

2 unique digits that is assigned to the airline.

name
string

Name of the airline.

status
string
Enum: "ACTIVE" "PASSIVE"

Specifies the trackability status of the airline

  • Active – The airline is trackable.
  • Passive – The airline is not trackable.

Note: Airline status may change.

prefixes
Array of strings

The air waybill(AWB) prefix(es) for the airline.

object

Meta information about the returned list.

more
boolean

Indicates whether there are more resources to fetch.

total
integer or null

Indicates the total number of resources, it's only available when there is no more resources.

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "airlines": [
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ],
  • "meta": {
    • "more": true,
    • "total": null
    }
}

AIR - Shipments

This section provides a comprehensive set of endpoints to manage your air shipments.

How It Works

First, you need to create the shipment, and after that, we will periodically check the shipment status and other relevant details. Our system will automatically track the shipment's progress and any changes, ensuring everything stays updated. You will be notified with updates and changes as needed, ensuring timely and accurate information about your shipment. You can also check your shipment details at any time, or use webhooks (available soon) to receive real-time updates.

AIR - Create a shipment

This endpoint allows you to create a new shipment by providing the necessary shipment details. Once the shipment is successfully created, you need to save the given shipment identifier in your internal system to use it across the related endpoints.

Duplicate Shipments

If there is an another shipment with the same reference and awb_number, the shipment will not be created (there is no cost), and the system will return a response (409 - ALREADY_EXISTS) indicating details of the existing shipment. If you don't provide a reference field on your request, the system will only check with the awb_number.

Note: If you want to add a follower or tag to the existing shipment, you must make new request(s) to related endpoints using the existing shipment's id.

Concurrent Requests

We process creation requests one by one for your company to prevent race conditions, such as misusing your credits or creating unnecessary duplicate shipments. You don't need to take any action, this process is handled entirely by Shipsgo system. However, sending too many concurrent requests can result in longer wait times and errors (429 - TOO_MANY_CONCURRENT_REQUESTS). If you plan to create a large number of shipments at once, ensure that requests are sent synchronously.

Authorizations:
Shipsgo User Token
Request Body schema: application/json
required
reference
string [ 5 .. 128 ] characters

Your reference to remember or classify the shipment. You can enter any numbers or letters.

Note: Also it will be the default title of tracking notification emails.

awb_number
required
string^[0-9]{3}(-)?[0-9]{8}$

The Air Waybill (AWB) number provided by the airline and required to track the shipment.

Note: To avoid any confusion, our system will standardize the AWB number with a separating hyphen (333-88888888).

followers
Array of strings <= 10 items

Email addresses subscribed to receive notifications about the shipment.

tags
Array of strings <= 10 items [ items <= 64 characters ]

A list of labels or keywords associated with the shipment. Used to include additional information to the shipment in order to differentiate, identify and categorise your shipments.

Responses

Response Headers
X-Shipsgo-Credits-Cost
integer
Example: "2"

The amount of credit consumption for the operation.

X-Shipsgo-Credits-Remaining
integer
Example: "1000"

The amount of credit remaining after the operation.

Response Schema: application/json
message
string

A message indicating the result (SUCCESS).

object
id
integer

The unique identifier of the shipment.

reference
string

Your reference to remember or classify the shipment.

awb_number
string

The Air Waybill (AWB) number provided by the airline and required to track the shipment.

Request samples

Content type
application/json
{
  • "reference": "INTERNAL_UNIQUE_IDENTIFIER",
  • "awb_number": "333-88888888",
  • "followers": [
    • "customer-1@example.com",
    • "customer-2@example.com"
    ],
  • "tags": [
    • "IMPORT",
    • "CUSTOMER_ABC"
    ]
}

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "shipment": {
    • "id": 123456,
    • "reference": "INTERNAL_UNIQUE_IDENTIFIER",
    • "awb_number": "333-88888888"
    }
}

AIR - List of shipments

The shipments list endpoint allows you to retrieve a list of your shipments (basic information). This includes options to apply various filters and sorting. To access detailed information (status_extended, movements, followers, etc.) about a shipment, you should use the AIR - Details of the shipment endpoint.

Example #1: Ongoing (EN_ROUTE) shipments carried by TURKISH CARGO (TK) or LUFTHANSA CARGO (LH) with upcoming arrivals in order.

/air/shipments
  ?filters[status]=eq:EN_ROUTE
  &filters[airline]=in:TK,LH
  &order_by=date_of_rcf,asc

Example #2: Shipments that were shipped to India (IN), between September 1, 2024, and October 1, 2024 in order.

/air/shipments
  ?filters[destination_country]=eq:IN
  &filters[date_of_dep]=between:2024-09-01...2024-10-01
  &order_by=date_of_dep,asc

Example #3: Shipments tagged with COMPANY_ABC and created by John Doe (john-doe@example.com).

/air/shipments
  ?filters[tags]=with:COMPANY_ABC
  &filters[creator]=eq:john-doe@example.com
Authorizations:
Shipsgo User Token
query Parameters
object <Dictionary<string, string>>

You can use the following filters with their respective operators. Common structure is filters[field]=operator:value(s).

Field Operators Description
id eq Unique identifier for the shipment.
status eq, not_eq, in, not_in Enum: NEW, INPROGRESS, BOOKED, EN_ROUTE, LANDED, DELIVERED, UNTRACKED
airline eq, not_eq, in, not_in The IATA code of the airline(s). Ex: TK, QR, AF, LH
awb_number eq Value format must be 333-88888888 or 33388888888.
reference eq, contains, not_contains Custom reference used to classify shipment(s).
status_split eq Boolean (true or false).
origin_port eq, not_eq, in, not_in The IATA code of the airport(s). Ex: IST, MIA, FRA
date_of_dep eq, gt, gte, lt, lte, between Departure date in ISO 8601 format.
origin_country eq, not_eq, in, not_in The unique 2-letter code identifying the country. Ex: TR, US, ES
destination_port eq, not_eq, in, not_in The IATA code of the airport(s). Ex: IST, MIA, FRA
date_of_rcf eq, gt, gte, lt, lte, between RCF date in ISO 8601 format.
destination_country eq, not_eq, in, not_in The unique 2-letter code identifying the country. Ex: TR, US , ES
followers with, without Valid email addresses.
tags with, without Labels or keywords associated with the shipment(s).
creator eq, not_eq, in, not_in Valid email addresses.
created_at eq, gt, gte, lt, lte, between Creation date in ISO 8601 format.
updated_at eq, gt, gte, lt, lte, between Update date in ISO 8601 format.
checked_at eq, gt, gte, lt, lte, between Last check date in ISO 8601 format.
discarded_at eq, gt, gte, lt, lte, between Discard date in ISO 8601 format.

Note: You can specify a timezone for date fields; if no timezone is provided, they will be considered as UTC.

order_by
string

You can sort the list with following fields. Common structure is order_by=field,direction.

Field Description
id Unique identifier for the shipment.
status Current status of the shipment.
airline Associated airline for the shipment.
date_of_dep Departure (DEP) date of the shipment.
date_of_rcf Received from flight (RCF) date.
created_at Date and time the shipment was created.
updated_at Date and time the shipment was last updated.
checked_at Date and time the shipment was last checked.

Note: By default the results are ordered by the created_at in desc (descending) order.

skip
integer >= 0

The number of records to skip before returning the results. The default value is 0.

take
integer [ 1 .. 100 ]

The number of records to return. The default value is 25.

Responses

Response Schema: application/json
message
string

A message indicating the result (SUCCESS).

Array of objects

List of shipments.

Array
id
integer

The unique identifier of the shipment.

reference
string

Your reference to remember or classify the shipment.

awb_number
string

The Air Waybill (AWB) number provided by the airline.

object or null

The airline that is responsible for the shipment.

object

The quantitative properties of the shipment.

status
string
Enum: "NEW" "INPROGRESS" "BOOKED" "EN_ROUTE" "LANDED" "DELIVERED" "UNTRACKED"

The status to represent current state of the shipment.

  • NEW - The shipment has not been checked by the Shipsgo system yet.
  • INPROGRESS - The airline hasn't provided any information about the shipment yet. Shipsgo system will continue to check periodically.
  • BOOKED - The shipment has been reserved with the airline for transport, but it has not yet been loaded or dispatched.
  • EN_ROUTE - The shipment is in transit and on its way to the final destination.
  • LANDED - The shipment's flight has arrived at the destination airport.
  • DELIVERED - The shipmen has been completed and delivered to consignee.
  • UNTRACKED - There is no available tracking information for the shipment. The AWB number might be invalid, or the airline may not have a public tracking system.
status_split
boolean

It states whether the shipment is split/partial cargo or not.

object or null

The route details of the shipment, including origin, destination, and transit information.

Array of objects

A list of labels or keywords associated with the shipment.

created_at
string

Creation date of the shipment (UTC).

updated_at
string

Date of the last update (UTC). It only covers movement and status changes.

checked_at
string or null

Date of the last time shipment checked by Shipsgo (UTC).

discarded_at
string or null

Indicates the timestamp (UTC) when the shipment was marked as discarded from the system's active control queue. Once a shipment is discarded, the system will no longer track or update the shipment. If it's null (empty), it means the shipment is still actively being tracked, and the system will continue to update it.

object

Meta information about the returned list.

more
boolean

Indicates whether there are more resources to fetch.

total
integer or null

Indicates the total number of resources, it's only available when there is no more resources.

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "shipments": [
    • {
      },
    • {
      },
    • {
      }
    ],
  • "meta": {
    • "more": false,
    • "total": 3
    }
}

AIR - Details of the shipment

This endpoint retrieves the details of an existing air shipment. It returns comprehensive information about the shipment. This allows users to track and monitor the shipment's progress and status in real-time.

Authorizations:
Shipsgo User Token
path Parameters
shipment_id
required
integer

The unique identifier of the shipment.

Responses

Response Schema: application/json
message
string

A message indicating the result (SUCCESS).

object
id
integer

The unique identifier of the shipment.

reference
string

Your reference to remember or classify the shipment.

awb_number
string

The Air Waybill (AWB) number provided by the airline.

object or null

The airline that is responsible for the shipment.

object

The quantitative properties of the shipment.

status
string
Enum: "NEW" "INPROGRESS" "BOOKED" "EN_ROUTE" "LANDED" "DELIVERED" "UNTRACKED"

The status to represent current state of the shipment.

  • NEW - The shipment has not been checked by the Shipsgo system yet.
  • INPROGRESS - The airline hasn't provided any information about the shipment yet. Shipsgo system will continue to check periodically.
  • BOOKED - The shipment has been reserved with the airline for transport, but it has not yet been loaded or dispatched.
  • EN_ROUTE - The shipment is in transit and on its way to the final destination.
  • LANDED - The shipment's flight has arrived at the destination airport.
  • DELIVERED - The shipmen has been completed and delivered to consignee.
  • UNTRACKED - There is no available tracking information for the shipment. The AWB number might be invalid, or the airline may not have a public tracking system.
status_split
boolean

It states whether the shipment is split/partial cargo or not.

object <Dictionary<string, integer>>

Shipment status based on number of pieces. Each key of the object is one of the status values.

In the case of a split shipment, this field will be helpful for you to monitor the different statuses of the pieces.

Example #1: Out of 5 pieces, 5 pieces are EN ROUTE.

{
    "EN_ROUTE": 5
}

Example #2: Out of 5 pieces, 3 pieces are EN ROUTE, 2 pieces have LANDED.

{
    "EN_ROUTE": 3,
    "LANDED": 2
}
object or null

The route details of the shipment, including origin, destination, and transit information.

Array of objects

A list of movements, listing all the events that will occur or has occurred.

object <Dictionary<string, string>>

A list of tokens you can use to create publicly accessible links to the shipment.

Array of objects

Email addresses subscribed to receive notifications about the shipment.

Array of objects

A list of labels or keywords associated with the shipment.

object

Creator of the shipment.

created_at
string

Creation date of the shipment (UTC).

updated_at
string

Date of the last update (UTC). It only covers movement and status changes.

checked_at
string or null

Date of the last time shipment checked by Shipsgo (UTC).

discarded_at
string or null

Indicates the timestamp (UTC) when the shipment was marked as discarded from the system's active control queue. Once a shipment is discarded, the system will no longer track or update the shipment. If it's null (empty), it means the shipment is still actively being tracked, and the system will continue to update it.

Response samples

Content type
application/json
Example
{
  • "message": "SUCCESS",
  • "shipment": {
    • "id": 123456,
    • "reference": "INTERNAL_UNIQUE_IDENTIFIER",
    • "awb_number": "403-88888888",
    • "airline": {
      },
    • "cargo": {
      },
    • "status": "INPROGRESS",
    • "status_split": false,
    • "status_extended": { },
    • "route": null,
    • "movements": [ ],
    • "tokens": { },
    • "followers": [
      ],
    • "tags": [
      ],
    • "creator": {
      },
    • "created_at": "2020-01-31 12:00:00",
    • "updated_at": "2020-01-31 12:00:00",
    • "checked_at": "2020-01-31 12:00:00"
    }
}

AIR - Update the shipment

This endpoint allows users to update the fields of an existing air shipment.

Authorizations:
Shipsgo User Token
path Parameters
shipment_id
required
integer

The unique identifier of the shipment.

Request Body schema: application/json
required
reference
string

Your reference to remember or classify the shipment.

Responses

Response Schema: application/json
message
string

A message indicating the result (SUCCESS).

object
id
integer

The unique identifier of the shipment.

reference
string

Your reference to remember or classify the shipment.

awb_number
string

The Air Waybill (AWB) number provided by the airline and required to track the shipment.

Request samples

Content type
application/json
{
  • "reference": "INTERNAL_UNIQUE_IDENTIFIER"
}

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "shipment": {
    • "id": 123456,
    • "reference": "INTERNAL_UNIQUE_IDENTIFIER",
    • "awb_number": "333-88888888"
    }
}

AIR - Delete the shipment

This endpoint allows users to delete an existing air shipment.

Authorizations:
Shipsgo User Token
path Parameters
shipment_id
required
integer

The unique identifier of the shipment.

Responses

Response Schema: application/json
message
string

A message indicating the result (SUCCESS).

Response samples

Content type
application/json
{
  • "message": "SUCCESS"
}

AIR - Add follower to the shipment

This endpoint allows users to add a new follower to an existing air shipment.

Authorizations:
Shipsgo User Token
path Parameters
shipment_id
required
integer

The unique identifier of the shipment.

Request Body schema: application/json
required
follower
string

The new follower’s email address that you want to add to the shipment.

Responses

Response Schema: application/json
message
string

A message indicating the result (SUCCESS).

object
id
integer

The unique identifier for the follower.

email
string

The email adress that will be notified about the shipment.

Request samples

Content type
application/json
{
  • "follower": "customer-1@example.com"
}

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "follower": {
    • "id": 1001,
    • "email": "customer-1@example.com"
    }
}

AIR - Remove follower from the shipment

This endpoint allows users to remove an existing follower from an existing air shipment.

Authorizations:
Shipsgo User Token
path Parameters
shipment_id
required
integer

The unique identifier of the shipment.

follower_id
required
integer

The unique identifier of the follower.

Responses

Response Schema: application/json
message
string

A message indicating the result (SUCCESS).

Response samples

Content type
application/json
{
  • "message": "SUCCESS"
}

AIR - Add tag to the shipment

This endpoint allows users to add a tag to an existing air shipment.

Authorizations:
Shipsgo User Token
path Parameters
shipment_id
required
integer

The unique identifier of the shipment.

Request Body schema: application/json
required
tag
string <= 64 characters

The new tag (a label or keyword) that you want to add to the shipment.

Responses

Response Schema: application/json
message
string

A message indicating the result (SUCCESS).

object
id
integer

The unique identifier for the tag.

name
string

Name of the tag.

Request samples

Content type
application/json
{
  • "tag": "IMPORT"
}

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "tag": {
    • "id": 1001,
    • "name": "IMPORT"
    }
}

AIR - Remove tag from the shipment

This endpoint allows users to remove an existing tag from an existing air shipment.

Authorizations:
Shipsgo User Token
path Parameters
shipment_id
required
integer

The unique identifier of the shipment.

tag_id
required
integer

The unique identifier of the tag.

Responses

Response Schema: application/json
message
string

A message indicating the result (SUCCESS).

Response samples

Content type
application/json
{
  • "message": "SUCCESS"
}