Looking for the legacy API documentation? Click here

Shipments API Specification

Overview

The Shipments API enables customers to programmatically create new shipments within Maersk’s system.

To use this API, you must have a CoPilot account. For more details, please contact your Maersk sales representative.

Getting Started

Environments

The API is available in the below environments. Ensure you are using the appropriate environment for testing and live operations.

Environment Base URL
Production https://api.maersk.com/mgf/public-gateway
Testing https://api-stage.maersk.com/mgf/public-gateway

API Reference

For detailed information regarding request/response bodies, required fields, and the OpenAPI specification, please refer to the API reference documentation:

Environment API Reference URL
Production https://api.maersk.com/mgf/public-gateway/scalar/v1/#tag/shipments
Testing https://api-stage.maersk.com/mgf/public-gateway/scalar/v1/#tag/shipments
Name Method Path Description
CreateShipment POST /shipments Creates a shipment in the system.
GetLocationServiceCodes GET /locations/{locationId}/service-codes Retrieves a list of all valid service codes associated with the specified locationId.
GetLocationTariffServiceCodes GET /locations/{locationId}/tariffs/{tariffCode}/service-codes Retrieves a list of all valid service codes associated with a specified locationId and tariffCode

Key Request Fields

When creating a shipment, the following fields are especially important and are linked to your CoPilot account. To obtain the correct values, navigate to Settings > API Configuration in your CoPilot account.

  • locationId (Required): Unique identifier associated with your CoPilot account.
  • tariffCode (Optional): Should be populated if a value is specified under your CoPilot account. If there are multiple, reach out to your Maersk sales representative for clarification on which one to use.
  • controlStation (Optional): Should be populated in the request if it is specified under your CoPilot account.

All required request fields are indicated in the API Reference. However, some fields have special behavior, as detailed below.

  • housebill (Optional): The tracking number for your shipment. If omitted, a value will be auto-generated. If you have a reserved housebill range with Maersk, you can provide the next available housebill from that range. If the specified housebill is already taken, the system will generate a new one and return the final assigned housebill in the response.
  • serviceCode: (Required): Should be a valid service code. If you’re providing a tariffCode, this must also be a valid service under that tariff. See GetLocationServiceCodes and GetLocationTariffServiceCodes.

Authentication

This API utilizes OAuth 2.0 authentication with the client_credentials grant type. To obtain access credentials, please contact your Maersk sales representative.

Authentication Steps

  1. Get an access token:
    • Send a POST request to the token endpoint (see Token Endpoints) with your client credentials.
    • If successful, you’ll receive an access_token in the response.
  2. Use the access token:
    • Include the access_token value in the Authorization header: 
      Authorization: Bearer YOUR_ACCESS_TOKEN
    • Important: You must also include your client_id in the Consumer-Key header for every request: 
       Consumer-Key: YOUR_CLIENT_ID

Example access token request:

POST /oauth2/token HTTP/1.1
Host: https://api.maersk.com
Content-Type: application/x-www-form-urlencoded
client_id = YOUR_CLIENT_ID &
client_secret = YOUR_CLIENT_SECRET &
grant_type = client_credentials

Example access token response:

{
  "access_token": "eyJ0...",
  "scope": "openid",
  "id_token": "eyJ0...",
  "token_type": "Bearer",
  "expires_in": 7199
}

Token Endpoints

The below endpoints should be used respective of the environment you are sending requests to.

Environment Token Endpoint
Production https://api.maersk.com/oauth2/access_token
Testing https://api-stage.maersk.com/oauth2/access_token

Versioning

API versioning is implemented using the Api-Version header to ensure backward compatibility while allowing for improvements and new features to be introduced without disrupting existing integrations. If the Api-Version header is omitted, the request will default to the latest stable version.

Example:

Api-Version: 1

Error Handling

The API returns a standardized response object for structured errors across all endpoints. Errors are provided in a JSON format with detailed information to aid in debugging.

Example Error Response 

{
  "httpMethod": "POST",
  "requestUri": "https://api.maersk.com/mgf/public-gateway/shipments",
  "statusCode": 400,
  "statusText": "Bad Request",
  "errorMessage": "Validation Error(s)",
  "correlationIdentifier": "00-004a8d8690078d85bc8f92b156072a25-9782db54b2045007-01",
  "errorTimestamp": "2025-03-05T02:51:56.7724601Z",
  "detailedErrors": [
    {
      "path": "$.shipDate",
      "field": "shipDate",
      "value": "3/2/2025",
      "message": "'shipDate' cannot be in the past."
    }
  ]
}

Common Error Codes

Status Code Meaning Possible Causes
400 Bad Request Invalid input data, missing required fields
401 Unauthorized Missing or invalid authentication token
403 Forbidden Insufficient permissions
404 Not Found Resource does not exist
500 Internal Server Error Unexpected API error