The response provides a list of configured carriers, along with general information and their key. The key identifies the implementation fulfillmenttools uses when this carrier is employed to, for example, issue a label request or set up a track and trace connection for a parcel.
A more detailed view of a configured carrier can be obtained by requesting a specific carrier instance.
As shown in the request, some configurations for this carrier are provided upon creation. Some of the notable attributes include:
Attribute
Description
defaultParcelWeightInGram
This value depicts, no surprise here, the default value (1000 gram) to a parcel advised using this carrier. However, the actual weight might be overwritten by the actual call for the creation of a parcel (see add Parcel in our API Specification).
parcelLabelClassifications
This array of values describes which parcel dimensions should be selectable by a client when issuing a parcel. Please see, that these values are dependent on the carrier and your contract with it. It also maybe not be a mandatory value and could possibly be omitted. Duplicates are prohibited. An entry is considered as an duplicate, if the dimensions and the services are equal.
credentials
The credentials that are used to connect to the carriers' API. Which kind of credentials is needed depends on the carrier (selected by the attribute key. In this case the DHL API in Version 2 is selected. Thus we need to provide an API Key. Also there is (especially for DHL) the possibility to provide Fallback Credentials using the legacy DHL API ("DHL Geschäftskunden API" in this case.)
logoUrl
This optional attribute can be used to set a specific logo to a custom carrier or to overwrite the fallback logos for standard carriers provided by fulfillmenttools if needed.
Carrier-specific configuration
Depending on the carrier implementation (identified by the key), additional configuration may be required to operate the carrier.
The returnLabel attribute is a key configuration. It instructs fulfillmenttools whether to create a return label with every shipping label requested from the carrier.
Diagram showing the relationship between a tenant, multiple carriers, and multiple facilities. A carrier can be connected to one or more facilities.
In the context of carrier services, a facility is a location where courier, express, and parcel (CEP) services pick up parcels or where inter-facility transfers begin or end. Carriers can be assigned to one or more facilities. This information enables a fencing strategy, which allows routing orders to a facility where the required carrier is active.
Carriers enabled at the tenant level must also be enabled for the specific facilities where they are available. The facility-to-carrier connection includes configurations that allow for frictionless carrier services.
Attribute
Description
cutoffTime
The cut-off time (hour and minute) describes the time when the carrier usually arrives to collect parcels. This information is especially useful when configuring same-day deliveries, as it is crucial to finish any fulfillment process before the carrier's arrival.
deliveryAreas
This optional value is particularly relevant for custom and same-day carriers. It shows which target addresses (identified by an array of ISO 3166-1 alpha-2 country codes and their respective postal codes) are valid for a parcel sent via this carrier from the facility.
Connect an existing carrier to a facility
In this example, a [carrier] (https://docs.fulfillmenttools.com/documentation/developer-docs/more-integration-guides/carriers/introduction-to-carrier-configuration) and a [facility] (https://docs.fulfillmenttools.com/documentation/developer-docs/integration-guides/facilities) were already created:
Note the id of the facility (a81a1c85-cfe5-49d3-81d3-675154ef323e) and the id of the carrier (488bd1a6-6c76-4407-8dab-ece716dac14d). Both values are required to create a connection between the two entities.
Create the connection
Using both IDs in the target URL, the following call connects the carrier to the facility.
An empty deliveryAreas array indicates that there are no delivery target restrictions.
The cut-off time is set to 4:30 PM. In this example, this is the time the DHL driver typically arrives at the dark store to collect parcels.
As long as the Carrier and the FacilityCarrierConnection have the status ACTIVE, it is possible to create shipments and parcels with DHL as the CEP originating from this facility. See Create a shipment with parcels to track.
Create a shipment with parcels to track
Diagram showing that a single Shipment can contain one or more Parcels.
Before creating a parcel, it is important to understand two key entities: Shipment and Parcel.
Entity
Description
Parcel
A digital representation of a physical parcel that is advised or on its way to the consumer.
Shipment
A container for all parcels sent within a single process using the same carrier. Note: Certain data, such as dimensions or targetAddress, can be overridden at the parcel level.
Assuming a Facility has been connected to a Carrier, this use case demonstrates how to create a standalone shipment with two parcels, without a preceding PickJob or other leading entity. This demonstrates the flexibility of fulfillmenttools, where parts of the system, such as shipment creation, can be used independently to suit specific operational needs, like dynamically creating a shipment label for use in other systems.
Create a shipment for pickup
The following call creates a shipment to be picked up from facility 4fd70a59-9efe-40fd-808b-08ae86ca558f using the DHL carrier with ID 488bd1a6-6c76-4407-8dab-ece716dac14d.
The shipment contains references to the facility, the CEP, and the delivery address.
This shipment is not connected to an existing process. To associate it with a specific process, provide the processId in the request. Shipments can also be created during preceding processes, such as an order or PickJob, in which case data like the target address is inherited by the shipment created by fulfillmenttools.
With the shipment in place, a parcel can be created by issuing the following request.
This example shows the simplest way to create a parcel, where fulfillmenttools uses all necessary information from the corresponding shipment. However, it is possible to override data from the shipment for each created parcel, such as its dimensions, recipient, sender, or return address.
This creates the parcel entity with the status OPEN. Asynchronously, fulfillmenttools automatically advises the parcel label with the carrier. During this process, the parcel status transitions from OPEN to PROCESSING, and finally to DONE. The shipment status changes to CONFIRMED once all its associated parcels reach the DONE status.
Interpreting the result of a parcel request
Once the parcel status is DONE (successful) or FAILED, the result attribute contains the outcome.
The result object provides details about the outcome:
On success (status DONE), the object contains the carrierTrackingNumber, a trackingUrl, and URLs for the shipping label (sendLabelUrl) and any other relevant documents (labelUrl), such as delivery notes or return labels.
On failure (status FAILED), the summary attribute contains information about the cause of the failure. This error message usually originates from the carrier, and fulfillmenttools has limited control over its content.
In this successful case, the shipping label can be downloaded with the following call.
It is also possible to request services when creating an order. In the order payload, services can be listed for each entry in preferredCarriersWithProduct.
Create an order with a special service
curl --location --globoff '{{host}}/api/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {authToken}' \
--data-raw '{
"orderDate": "2023-03-11T08:16:07.000Z",
"deliveryPreferences": {
"shipping": {
"preferredCarriersWithProduct": [
{
"carrierKey": "BPOST",
"carrierServices": [
"SIGNATURE"
]
}
]
}
},
"consumer": {
"email": "[email protected]",
"addresses": [
{
"salutation": "Dhr.",
"firstName": "Jean",
"lastName": "Peeters",
"street": "Breidelstraat",
"houseNumber": "2",
"postalCode": "8000",
"city": "Brugge",
"country": "BE",
"emailAddress": "[email protected]",
"additionalAddressInfo": "637148",
"phoneNumber": "526-640-7512",
"addressType": "POSTAL_ADDRESS"
}
]
},
"tenantOrderId": "FC-4711-2361",
"status": "OPEN",
"orderLineItems": [
{
"article": {
"tenantArticleId": "2020249",
"title": "T-Shirt \"Am Sonnenhut\"",
"imageUrl": "https://d358g9injarr4u.cloudfront.net/res/product_1000/240eadd8-8f50-479d-b0d8-74412bd4a9f9.jpg",
"attributes": [
{
"category": "miscellaneous",
"key": "BRAND",
"value": "Adidas"
},
{
"category": "descriptive",
"priority": 100,
"key": "%%subtitle%%",
"value": "Neu!"
},
{
"category": "descriptive",
"priority": 200,
"key": "Mitgliederpreis",
"value": "17,96 EUR"
},
{
"category": "descriptive",
"priority": 300,
"key": "Schnitt",
"value": "Frauen"
},
{
"category": "descriptive",
"priority": 400,
"key": "Material",
"value": "100% Baumwolle"
},
{
"category": "descriptive",
"priority": 500,
"key": "Artikelnummer",
"value": "2020249"
},
{
"category": "descriptive",
"priority": 600,
"key": "Größe",
"value": "S"
},
{
"category": "descriptive",
"priority": 700,
"key": "Beschreibung",
"value": "Rotes T-Shirt mit weißen Streifen an den Ärmeln, Blockdruck mit Schriftzug auf der Brust"
}
]
},
"quantity": 1,
"scannableCodes": [
"2020249"
]
},
{
"article": {
"tenantArticleId": "2010681",
"title": "Steppjacke \"Mühlenbach\"",
"imageUrl": "https://d358g9injarr4u.cloudfront.net/res/product_1000/9fcb7e42-7c84-4ab0-999a-869efe077e0a.jpg",
"attributes": [
{
"category": "descriptive",
"priority": 100,
"key": "%%subtitle%%",
"value": "Neu!"
},
{
"category": "descriptive",
"priority": 200,
"key": "Größe",
"value": "L"
},
{
"category": "descriptive",
"priority": 300,
"key": "Oberstoff",
"value": "100% Polyester"
},
{
"category": "descriptive",
"priority": 400,
"key": "Futter",
"value": "100% Polyester"
},
{
"category": "descriptive",
"priority": 500,
"key": "Füllung",
"value": "100% Polyester"
},
{
"category": "descriptive",
"priority": 600,
"key": "Beschreibung",
"value": "Dreifarbige Steppjacke mit verstaubarer Kapuze, Zwei Eingriffstaschen, Gesticktes Logo auf der Brust"
},
{
"category": "descriptive",
"priority": 700,
"key": "Artikelnummer",
"value": "2010681"
}
]
},
"quantity": 1,
"scannableCodes": [
"2010681"
]
},
{
"article": {
"tenantArticleId": "5020064",
"title": "Wandtattoo Stadion",
"imageUrl": "https://d358g9injarr4u.cloudfront.net/res/product_1000/343f4569-66bb-4b0c-aa2b-20011a51b620.jpg",
"attributes": [
{
"category": "descriptive",
"priority": 100,
"key": "Maße",
"value": "70 x 50 cm"
},
{
"category": "descriptive",
"priority": 200,
"key": "Beschreibung",
"value": "Wandtattoo in Ziegelwand-Optik, Mit tollem Blick aufs Stadion"
},
{
"category": "descriptive",
"priority": 300,
"key": "Anwendung",
"value": "Für die Beklebung sollte die Fläche staub- und fetfrei sein. Bringen Sie den Aufkleber in Position und reiben Sie diese gleichmäßig mit der flachen Hand an den Untergrund, um sie zu fixieren. Jede Stelle nochmals gest andrücken. Fertig! Für auftretende Schäden nach der Verklebung auf dem Untergrund etc. ist eine Haftung ausgeschlossen."
},
{
"category": "descriptive",
"priority": 400,
"key": "Artikelnummer",
"value": "5020064"
}
]
},
"quantity": 2,
"scannableCodes": [
"5020064"
]
}
],
"paymentInfo": {
"currency": "EUR"
}
}'
Only services offered by the chosen carrier are applied when creating a parcel. A request for a service that the carrier does not offer will be ignored.
Setting carrier URLs
The URLs for carrier APIs (e.g., sandbox or production endpoints) can be configured at different levels. Carrier-specific URLs can be set tenant-wide to apply to all facilities, or they can be overridden for specific facilities. Set the URLs by configuring either the carrier or the facility-carrier connection, as shown in the following sections.
Carrier-level URLs
Setting URLs at the carrier level applies them to every facility where that carrier is used. Use the following endpoint to set the configuration. The following example demonstrates how to set the serviceUrl and trackAndTraceUrl for a DHL carrier.
Setting URLs at the facility-carrier level overrides any URLs set at the carrier level for that specific facility. Update the configuration in the facility-carrier connection using the following endpoint. This example shows how to set the URLs for a GLS carrier.
Non-delivery days can be configured for each carrier. This information is then used to calculate estimated delivery times and available delivery days. Non-delivery days can be specific calendar dates (e.g., 01/01/2025) or recurring weekdays (e.g., SUNDAY).
Non delivery days can be either specific calender dates (i.e. 01.01.2025) or weekdays (i.e. SUNDAY). While weekdays are always recurring (recurringNonDeliveryWeekdays), a specific calendar date can be set up as RECURRING or SINGLE by using the nonDeliveryType.
