fulfillmenttools offers a convenient way to send and track parcels. This page tells you more about the utilization of this feature.
fulfillmenttools can connect to various carriers allowing you to create shipments and corresponding parcels. Please clarify beforehand which carriers should be made available to your instance.
However, the usage of existing & ready to use carriers is similar and can be used no matter how many carriers you operate.
Entities of importance in this context
Carrier
Courier, Express and Parcel Services (or in Short: CEP) refer to entities, that are in general configured in fulfillmenttools. It depends on your setup which CEP Providers are available & ready to use. The API description including some documentation about the used attributes can be found in our API reference
To get a list of available carriers you can issue the following call:
The response gives you a list of configured carriers, along with some general information and their key, which describes which kind of implementation is chosen by fulfillmenttools whenever this carrier is used to, for example, issue a label request or setup track and trace connection for a parcel. You can get a more detailed look at a configured carrier by requesting one identified carrier instance, for example:
A Carrier instance is a singleton in any given fulfillmenttools platform. That means in general it can exist exactly once per tenant.
As you can see in the above response there are some configurations made to this exact carrier (DHL in this case). These configurations can be done on every carrier instance (check Add Carrier for details or continue reading.
Creation of a carrier
A carrier can be created by issuing the following call:
As you can see there are already some configurations to this carrier provided upon creation. Some of the interesting data is
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.
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 used Carrier implementation (depicted by the tag key) some additional configuration can be used to successfully operate a carrier:
One of the most important configurations is the attribute returnLabel in a given configuration. It tells fulfillmenttools whether a return label should be created with every label requested from the given carrier.
This resource describes the stores, warehouses, popup stores, locations, etc. of the fulfillment network. In general, a facility is a place where fulfillment processes take place or should be considered. Details see use case Add and Manage Facilities
In this carrier services related use case a facility is a place where CEP services pick up parcels or inter facility transfers are started / finished.
Connection between a Facility and a Carrier
The Facility-To-Carrier-Connection is (some people already understood) the connection between a facility and a carrier. Many configurations that allow for frictionless carrier services have to be configured here. Please refer to FacilityCarrierConnection for detailed information on every attribute. Here are some of the attributes worth mentioning:
Attribute
Description
cutoffTime
Value (hour and minute) describe the time when the carrier (usually) shows up to take parcels with him. This information is especially useful when configuring SAMEDAY deliveries as it is crucial to have finished any fulfillment process until the arrival of the carrier.
deliveryAreas
This optional value might be of special interest to Custom Carriers and specific SAMEDAY carriers. It shows which target addresses (identified by an array of ISO 3166-1 alpha-2 conform country codes and their respective postalcodes) can be a valid target to a parcel sent via this carrier from the facility.
Concept: Custom Carrier
Apart from the provided carrier connection to many "mainstream" carriers fulfillmenttools offers another flavor of carriers: The so called Custom Carrier. Those represent a carrier that is not natively supported by fulfillmenttools but is still used in the field.
Some examples for a custom carrier setup could be
Sending parcels via a local bike carrier, that is called by phone or messenger or whatever when needed
the shop owner, who takes parcels to a local carrier pickup point whenever it suits the operational process (maybe on his way home after work)
an own carrier fleet that delivers goods on its own schedule using detached tooling (like a standalone routing service & delivery app)
It is possible to create several custom carriers.
Since the carrier key must be unique a custom carrier must have the key starting with "CUSTOM" followed by any appendix (e.g. CUSTOM_FORWARDINGAGENCY, CUSTOM_COURIER,...)
Available Carriers
Currently fulfillmenttools supports the following carriers. Please note, that this list is constantly extended. Please get in contact with us in case you need a specific not yet implemented carrier.
Only from certain metropolitan areas within Germany to specific target postal codes (depending on originating metro area).
Sameday - what does this mean?
The idea of sending goods not only from a centralized warehouse but from a brick and mortar store next to the customer opens up more possibilities to offer services like Same Day delivery or event instant delivery.
Fulfillmenttools supports this by offering an endpoint which allows a checkup for delivery options like Same Day within the customer’s checkout process in the shop system.
Our fulfillment options endpoint (see: fulfillment options) is able to check for Same Day options within the network on the basis of the input parameters: estimated order date, address of the customer, service level (best effort e.g. sfs or Same Day) and (optional) the basket of the customer (ordered items).
The check takes into account whether
a facility exists which has the service type ship-from-store and at least one Same Day carrier
the Same Day carrier delivers into the area the customer lives in
there is enough time to fulfill and deliver the goods to the customer. This is done by verify whether the process (process time can be set - we call this fulfillment buffer) can be performed within the fulfillment times and is finished before the carrier picks up the order.
optionally: the ordered articles are in stock (our offlinestock as well as reserved stock are taken into consideration)
If there is a positive Same Day check-up result our endpoint communicates this and the shop can now allow the customer to select this option. We make this option only valid for a certain timespan, otherwise the temporal circumstances changes and Same Day delivery might not be possible anymore.
The “valid until” time is calculated like this:
cut off time of the selected carrier - fulfillment time
In case multiple facilities are available, the one with the youngest carrier cutoff time is chosen so that there might be some time left in case a reroute is necessary.
We make sure that this check-up is performed just within seconds, since the customer should not wait for the options to select.
Connect an existing carrier to a facility
Let's assume that we have a facility (see Add and Manage Facilities) and a carrier (see Creation of a carrier) already created. Lets receive the correspondent entities first (omitting some of the attributes):
curl-sSL'https://your.api.fulfillmenttools.com/api/facilities/a81a1c85-cfe5-49d3-81d3-675154ef323e' \--header'Authorization: Bearer <TOKEN>'200OK{"id":"a81a1c85-cfe5-49d3-81d3-675154ef323e","name":"Darkstore Cologne","address":{"street":"Schanzenstr.","houseNumber":"8-20","postalCode":"51063","city":"Cologne","country":"DE","companyName":"fulfillmenttools","resolvedCoordinates":{"lon":7.013988,"lat":50.964969 },"resolvedTimeZone":{"offsetInSeconds":3600,"timeZoneId":"Europe/Berlin","timeZoneName":"W. Europe Standard Time" },... },"locationType":"WAREHOUSE","services": [ {"type":"PICKUP" }, {"type":"SHIP_FROM_STORE" } ],"status":"ONLINE","created":"2022-12-20T10:00:48.419Z","lastModified":"2023-03-27T14:13:51.213Z","version":6,...}
Please take note of two important parameters we are going to use in the following: The id of the facility (a81a1c85-cfe5-49d3-81d3-675154ef323e in this case) and the id of the carrier (488bd1a6-6c76-4407-8dab-ece716dac14d). We need both values in order to create a connection between those two entities.
The Connection
By using both values in our target URL the following call we configure the carrier to said facility:
The empty array of the attribute deliveryAreas indicates, that there are no restrictions regarding delivery targets.
We also conveniently set the cutoff time to 16:30, because in our fictive case this is the time when the DHL driver typically arrives at the Darkstore to pick up the parcels.
That's it: As long as the Carrier and the FacilityCarrierConnection stays in status "ACTIVE", it should be possible to create shipments and in the end also parcels using DHL as a CEP (see Create a shipment with parcels to track) originating from this facility.
Create a shipment with parcels to track
Before we dive into the process of sending a parcel we need to clarify two more entities: Shipment and Parcel.
Entity
Description
Parcel
A parcel is the digital representation of one physical parcel that is avised / on its way to the consumer.
Shipment
A shipment is the bracket around all parcels sent within a process using the same carrier. Please note: Certain data could vary from parcel to parcel: dimensions or targetAddress of the shipment can be overwritten in a parcel instance.
Let's assume we already connected a Facility with a Carrier using a FacilityCarrierConnection (see Connect an existing carrier to a facility). In this use case we are going to create a standalone shipment and two parcels - without having a Pickjob or any other leading entity. This is a perfect example on how flexible fulfillmenttools is: There might be standard processes, but you are also able to use parts of the system to suit your operational needs - like for example the need of dynamically create a Shipment Label for further use in other systems.
Create Shipment for pickup in a facility and by a carrier
With the following call we create a shipment to be picked up in facility with ID 4fd70a59-9efe-40fd-808b-08ae86ca558f using the DHL Carrier with ID 488bd1a6-6c76-4407-8dab-ece716dac14d:
As you can see: The shipment has knowledge about the facility, the CEP and the address where to deliver.
As mentioned above: This shipment is not connected to any existing process! If you want to create a shipment to a specific process you need to provide the attribute processId within the request. Also shipments can be created during preceding processes. In that case data like the target address is provided via the order or the pickjob to the shipment which is created by fulfillmenttools.
Having the Shipment in place we are now ready to create a parcel via this shipment by issuing the following request:
curl-sSL-XPOST'https://your.api.fulfillmenttools.com/api/shipments/3e62db41-af9e-4ce1-8c44-1ef340457057/parcels' \--header'Authorization: Bearer <TOKEN>'201Created{"loadUnitRefs": [],"version":1,"id":"713b9cd8-6d47-45ff-a12a-ef3acb270180","status":"OPEN","shipmentRef":"3e62db41-af9e-4ce1-8c44-1ef340457057","processRef":"3af2e1a7-d104-4ef9-a43b-13890ae318cf","carrierRef":"488bd1a6-6c76-4407-8dab-ece716dac14d","recipient":{"firstName":"Luke","lastName":"Skywalker","street":"Planetenstraße","houseNumber":"13","postalCode":"40223","city":"Düsseldorf","country":"DE" },"sender":{"street":"Carlsplatz","houseNumber":"3","postalCode":"40213","city":"Düsseldorf","country":"DE","companyName":"ptdus","resolvedCoordinates":{"lon":6.77285093516085,"lat":51.2263665950437 },"emailAddresses":null,"additionalAddressInfo":null,"phoneNumbers":null,"resolvedTimeZone":{"offsetInSeconds":3600,"timeZoneId":"Europe/Berlin","timeZoneName":"W. Europe Standard Time" } },"dimensions":{"weight":2000 },"created":"2023-04-14T15:03:07.982Z","lastModified":"2023-04-14T15:03:07.982Z"}
Please take note that we are issuing a parcel the most simple way in which fulfillmenttools will use all necessary information from the corresponding shipment. However, you are also able to overwrite certain data from the shipment for each created parcel, such as the dimensions, the recipient, the sender or return address.
We just created the entity that represents the parcel in status OPEN. Now, in an async matter, fulfillmenttools is automatically taking care of the actual advising of the parcel label. During the time it takes fulfillmenttools and the CEPs API to negotiate and create a parcel, the status of the parcel changes from OPEN via PROCESSING to finally DONE. The shipment also transparently changes its status to CONFIRMED as soon as all created parcels of the shipment reached the status DONE.
Interpreting the result of a parcel request
Once the parcel reached one of the status DONE (happy case) or FAILED it is time to take a look at the result attribute of the parcel:
The result in general shows details about the outcome of the request:
In case of a successful termination of the request towards this specific CEP API (see above) we can find the trackingNumber, a tracking URL, a label to download the sendLabel and also with the attribute labelUrl a document that consists of all the documents that are of importance to this parcel (such as for example deliveryNotes, return labels, etc.).
In case of a unsuccessful termination of the request the summary attribute carries information about the root cause of the failure. The contents of this error message usually originates from the carrier - fulfillmenttools has limited control about the data.
In this case we are ready to download the avised label using the following call:
It is also possible to pass the information directly when creating an order. In the order the services can be directly listed for each preferredCarrierWithProducts:
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": "ulf.steinke@ocff.de",
"addresses": [
{
"salutation": "Dhr.",
"firstName": "Jean",
"lastName": "Peeters",
"street": "Breidelstraat",
"houseNumber": "2",
"postalCode": "8000",
"city": "Brugge",
"country": "BE",
"emailAddress": "Jean.Peeters@yahoo.com",
"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 will be taken when creating a parcel. Providing a service for a carrier which does not offer that service will be ignored.
