API Endpoints Overview
The Offers API supports a number of endpoints related to Spot Offers. While some are only relevant to internal Maersk consumers, others can be consumed by Maersk customers or partners. See onboading guide to get setup for consuming the Offers API.
Backwards Compatibility & Versioning
We will do everything we can to maintain backwards compatibility when we update the API. However, we won't always get it right first time. When we don't, we need to provide you with an updated API without disrupting your current integration. To this end we have defined a few rules around backwards compatibility and versioning to make your life easier and more predictable.
To avoid integration troubles, make sure you are developing robust code by expecting the API to get updated with new parameters and/or additions to data models in the response. We have detailed the changes you can expect below, so you can understand how the API will change over time.
Read more in our description of API versioning and Backwards Compatibility.
Endpoint Groups
The Offers API is divided into groups of related endpoints. Below you will for each group of endpoints find a short description of the purpose of the endpoints together with a link to the detailed description of each endpoint. The description will also state if the endpoint is meant for Maersk internal use only or if it can be used by customer and 3rd party platforms. See API Security Tokens for more information about security requirements for calling endpoints.
If you find endpoints in the swagger documentation, that isn't mentioned here, then you should assumed that it is because it is not relevant or ready for non maersk internal use.
Product Offers endpoints
See Endpoints: Product Offers for details about the endpoints.
The Product Offers group of endpoints are concerned about which products are available on which combinations of origins, destinations and container size and types. The Product Offers group of endpoints also include an endpoint to get the combined information for available product offers for a certain combination origin, destination, container size and type. This combined information should include all the information relevant for a display of the offer to a customer, like which Product the offer is for, the route and schedule information for the offer, including relevant vessel departures and deadlines information for these, and also includes price information for the offer.
| Category of API consumer | Access control | Authentication needed |
|---|---|---|
| Maersk controlled sites | Allowed | ForgeRock JWT |
| Direct customers integrations | Allowed | Consumer key |
| 3rd party platforms | Allowed | Consumer key |
Product Definition endpoints
See Endpoints: Product Definition for details about the endpoints.
The Product Definition group of endpoints are concerned about which the details of products offered. The response data models for the Product Offers endpoints will contain data to identify the product offered, but will not contain the detailed information for the product. The endpoints in the Product Definition group of endpoints makes this information available. The definition for a Product is identified by the productCode and productVersion and the definition is immutable. In other words if the definition for a product is changed a new version is created, that will supplant the previous version of the product (except for smaller textual changes made for clarification purposes).
Bookings already placed with the definition for a retired product version is still subject to that product definition, which means an existing booking will not change terms and conditions, if a new version of the product is made available. This also means that two versions of a product can be valid at the same time, but only that latest version will be available on new offers.
| Category of API consumer | Access control | Authentication needed |
|---|---|---|
| Maersk controlled sites | Allowed | ForgeRock JWT |
| Direct customers integrations | Allowed | Consumer key |
| 3rd party platforms | Allowed | Consumer key |
Swagger
The Offers API also includes a api description in the Swagger 2.0 format. This description is generated by the application, and will always reflect the latest changes in the API endpoints.
The Offers API also bundles a Swagger UI for Offers API endpoints, which can be used to navigate the definition of the endpoints and see the request and response data models. The Swagger UI can also be used to execute calls to the Offers API endpoints in the environment it is accessed, however this requires relevant authentication credentials.