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.

Related Endpoints
Key Request Fields
Environments
Authentication
Versioning
Error Handling

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

API Reference

The interactive reference below is filtered to the Shipments and Locations tags so you can focus on the endpoints described on this page.

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 > Developer Console 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.
quoteId (Optional): Quote ID to associate with the shipment for auditing purposes. See Ratings API.
payType (Required): Specifies which party is responsible for paying the shipment charges. The paying party must exist in Maersk’s system as a customer. Address matching is performed against the party’s address fields, so you must provide the same address that appears in your CoPilot location settings (Settings > Locations & Security). Alternatively, you may provide the party’s addressId, which can be found in Settings > Developer Console. Refer to the table below for the supported pay types and their corresponding parties.

PayType	Party
`Prepaid`	`shipper`
`Collect`	`consignee`
`ThirdParty`	`thirdParty`

Environments & Authentication

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

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

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.
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 both the token request and all subsequent requests that use the access_token:

Consumer-Key: YOUR_CLIENT_ID

Example access token request:

POST /customer-identity/oauth/v2/access_token HTTP/1.1
Host: api.maersk.com
Content-Type: application/x-www-form-urlencoded
Consumer-Key: YOUR_CLIENT_ID

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

Use the corresponding token endpoint for the environment that matches your request.

Environment	Token Endpoint
Production	`https://api.maersk.com/customer-identity/oauth/v2/access_token`
Testing	`https://api-stage.maersk.com/customer-identity/oauth/v2/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