Custom carrier

You can create a custom carrier that is connected through an external service or operational process. This mechanism enables you to integrate:

• Local delivery partners (for example, bike couriers)

• Store operators who hand parcels to local drop-off points at flexible times

• Internal delivery fleets with independent routing systems and apps

This configuration is handled through the Custom Carrier API. Each custom carrier requires a unique key that begins with CUSTOM_ (for example, CUSTOM_BOSSONBIKE). This ensures uniqueness and simplifies operational identification. The key must be unique within the tenant. Reusing a key is not allowed.

Custom carriers must be connected to facilities to be considered during routing and shipment creation.

Multiple custom carriers

While it's not possible to have more than one provided carrier in fulfillmenttools, it's possible to configure multiple custom carriers. Since the carrier key is used for identification and thus must be unique, a custom carrier must have the key starting with CUSTOM_ followed by any appendix (e.g., CUSTOM_BOSSONBIKE) to ease identification.

Custom Carriers represent carriers that are not natively supported by fulfillmenttools, but are connected by an external service or operative process.

While it is not possible to have more than one provided carrier in fulfillmenttools, it is possible to configure multiple custom carriers. Since the carrier key is used for identification and thus must be unique, a custom carrier must have a key starting with CUSTOM_ followed by an appendix (e.g., CUSTOM_BOSSONBIKE) to ease identification.

Use case: Headless carrier connection

A custom carrier enables a proprietary carrier integration with the fulfillmenttools platform. This tutorial showcases a possible solution for integrating an unsupported carrier, detailing the required processes and clients.

The integration model allows for a headless connection by using fulfillmenttools eventing and API interactions. This enables an external service, implemented and operated by a partner or customer, to manage the complexities of requesting a shipping label from an arbitrary carrier.

Concept

The following diagram and explanation describe the overall approach.

A flowchart illustrating the five steps of the custom carrier integration concept, from event subscription in fulfillmenttools to setting handover states.

1. Subscribe to a fulfillmenttools event. The process is triggered by an event subscription. The specific event chosen depends on the customer's process, but a logical trigger would be an event that occurs after packing is complete, such as PACK_JOB_CREATED. fulfillmenttools sends this event to the external service that handles the label request from the Carrier API.

2. The external service gathers data and makes decisions. The external service receives the event and uses its payload to make decisions, such as selecting the exact carrier or carrier product, determining the necessary insurance value, etc. This data can be sourced from other services, a database, or fetched from fulfillmenttools via its API.

3. Request a label from the Carrier API. Similar to the native fulfillmenttools mechanism, the external service uses the gathered data to request a label and negotiate a pickup with the carrier. The service receives the label and other data (e.g., pickup dates, transit times) from the carrier.

4. Store the carrier label and data in fulfillmenttools. Once the label, track-and-trace information, and any additional data are received, the external service uploads this data to fulfillmenttools for seamless process integration. For example, the label is uploaded to a documentset, and the track-and-trace data is stored as a result on the parcel entity.

5. Set handover states based on track-and-trace data. fulfillmenttools can set the handover status of shipped parcels to "handed over." The external service can perform this action by connecting to the carrier's track-and-trace API and deciding when to set the handoverJob status in fulfillmenttools to HANDED_OVER, according to the desired process.

Proof of concept: Connecting Uber Direct

Overview

As a proof of concept, this section demonstrates how to connect the carrier Uber Direct to fulfillmenttools. An external service, the Uber Connector Service, will be created to manage the integration.

This example uses Uber Direct due to its straightforward technical connection. It can be substituted with any other carrier. For this proof of concept, specific parameters are chosen, such as the trigger event, required data, and handover timing. This represents one of many possible implementation strategies; the approach can be adapted with different event triggers or more complex logic as needed.

In this example, the Parcel (with its label PDF) is automatically ordered when a PackJob is created for a given Process. The following diagram illustrates the components and events involved.

A sequence diagram showing the interaction between fulfillmenttools, the Uber Connector Service, and the Uber Direct API.

Necessary steps

The integration connects to Uber Direct as the carrier, which offers a simple API for requesting pickups and deliveries.

The external service is hosted within a Google Cloud Project as a Cloud Run service, which scales to zero and responds to HTTP requests from a fulfillmenttools subscription.

Prepare the service infrastructure

This proof of concept is written in Kotlin. To create a running service, refer to the official Google Cloud documentation for deploying a Kotlin service to Cloud Run.

Platform Independence

The choice of hosting platform (e.g., GCP, Azure, AWS, on-premise) is irrelevant from an architectural standpoint. Any platform capable of hosting and operating the service may be used.

After completing this step, a live Cloud Run service is deployed and reachable via the internet without authentication on its endpoints.

Production Security

This proof of concept omits security measures for simplicity. A production-ready service must implement robust authentication and authorization mechanisms to protect its endpoints.

Configuration of fulfillmenttools

Following the guide on carrier management, create the custom carrier "Uber Direct" as shown below:

curl --location 'https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/carriers' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: ••••••' \
    --data '{
      "key": "CUSTOM_UBER",
      "name": "Uber Direct",
      "status": "ACTIVE"
    }'
< 201 Created
{
    "id": "26de36d7-883d-456a-91ef-ed9526cd5835",
    "key": "CUSTOM_UBER",
    "name": "Uber Direct",
    "status": "ACTIVE",
    ...
}

Next, connect this carrier to the facility where the service will be provided:

# 469adf78-5aeb-425c-b2dc-91027e69336a being the ID of the facility in this case
curl --location 'https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/facilities/469adf78-5aeb-425c-b2dc-91027e69336a/carriers/26de36d7-883d-456a-91ef-ed9526cd5835' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: ••••••' \
    --data '{
        "status": "ACTIVE",
        "name": "CUSTOM_UBER",
        "configuration": {
            "key": "CUSTOM_UBER"
        }
    }'

< 201 Created
{
    "id": "469adf78-5aeb-425c-b2dc-91027e69336a_26de36d7-883d-456a-91ef-ed9526cd5835",
    "version": 1,
    "name": "CUSTOM_UBER",
    "status": "ACTIVE",
    "carrierRef": "26de36d7-883d-456a-91ef-ed9526cd5835",
    "key": "CUSTOM_UBER",
    "deliveryType": "DELIVERY",
    "facilityRef": "469adf78-5aeb-425c-b2dc-91027e69336a",
    "configuration": {
        "key": "CUSTOM_UBER"
    },
    ...
}

Implement the Uber Carrier Connector Service

The service is designed as a standalone application that does not require a database or other external components besides its container engine. This requires making practical decisions about which event to use and how much processing to perform during the event handling.

The created service is now extended with the following functionality. Only subsets of the implementation are described here.

Implementing functionality for the Uber Direct API

First, an Uber account with access to the Uber Direct API is required. The following credentials must be obtained:

• A Customer ID (UBER_CUSTOMER_ID)

• A valid Client ID (UBER_CLIENT_ID)

• A matching client secret (UBER_CLIENT_SECRET)

For simplicity, a new Bearer Token for the Uber API (UBER_TOKEN, valid for 30 days) is generated via curl and provided as a configuration variable to the service. This call obtains the token:

> curl --location 'https://login.uber.com/oauth/v2/token' \
  --form 'client_id="UBER_CLIENT_ID"' \
  --form 'client_secret="UBER_CLIENT_SECRET"' \
  --form 'grant_type="client_credentials"' \
  --form 'scope="eats.deliveries direct.organizations"'
< 200 OK
{
    "access_token": "UBER_TOKEN",
    "token_type": "Bearer",
    "expires_in": 2592000,
    "scope": "eats.deliveries direct.organizations"
}

Next, the service must implement a call to Uber for the creation of a delivery (pickup at location A, drop-off at location B). To accomplish this, a new Uber API object and the implementation for the delivery creation endpoint are created:

Apis.kt

class Api {
    companion object Factory {
        fun createUberApi():UberApi = Retrofit.Builder()
                .addConverterFactory(GsonConverterFactory.create())
                .baseUrl("https://api.uber.com/v1/customers/UBER_CUSTOMER_ID/")
                .build().create(UberApi::class.java)
    }
}

UberApi.kt

interface UberApi {
    @Headers(
        "Authorization: Bearer UBER_TOKEN",
    )
    @POST("deliveries")
    fun createDelivery(@Body createDelivery: CreateDelivery): Call<CreatedDelivery?>
}

In addition, model classes for the request and response bodies, a repository, and a service are implemented for better code structure and readability.

Implement connections for the fulfillmenttools REST API

Functionality is also required to interact with fulfillmenttools to create parcels and set results. The following endpoints are the most important ones:

FFTApi.kt

interface FFTApi {
    @POST("shipments/{shipmentId}/parcels")
    fun createParcel(@Path("shipmentId") shipmentId: String, @Body parcelForCreation: ParcelForCreation): Call<Parcel>

    @GET("shipments")
    fun getShipments(@Query("pickJobRef") pickJobId: String): Call<Shipments>

    @PATCH("parcels/{parcelId}")
    fun patchParcel(@Path("parcelId") parcelId: String, @Body parcelPatch: ParcelPatch): Call<Parcel>

    @GET("handoverjobs")
    fun getHandoverJobs(@Query("shipmentRef") shipmentRef: String): Call<HandoverJobs>

    @POST("documentsets/{documentSetId}/documents")
    fun createDocument(@Path("documentSetId") documentSetId: String, @Body documentForCreation: DocumentForCreation): Call<Document>
    ...
}

In addition to creating a parcel in fulfillmenttools containing the result of the Uber delivery, the service also needs the ability to set the HandoverJob created in the process to HANDED_OVER:

interface FFTApi {
   ...
    @PATCH("handoverjobs/{handoverJobId}")
    fun patchHandoverJob(@Path("handoverJobId") handoverJobId: String, @Body handoverJobPatch: HandoverJobPatch): Call<HandoverJob>
}

Provide endpoints for fulfillmenttools and Uber events

With the functionality in place, the web endpoints can be defined to receive events from fulfillmenttools and Uber. An event from fulfillmenttools will trigger the creation of a delivery, while track-and-trace events from Uber will trigger further processing later in the flow.

@SpringBootApplication
@RestController
class Application {
    private val fftService: FulfillmenttoolsService = FulfillmenttoolsService() //the service to connect to fulfillmenttools
    private val uberService: UberService = UberService() //the service to connect to Uber direct
    private val pdfService: PdfService = PdfService() //a service that is able to create a PDF as base64

    /**
     * Callback for fulfillmenttools when a PackJob was created.
     */
    @PostMapping("/requestPickupCallback")
    suspend fun requestPickupCallback(@RequestBody packJobCreatedEvent: demo.fft.model.PackJobCreatedEvent) = run {
        //Authenticate @ fulfillmenttools
        if (!fftService.authenticate()) {
            return@run
        }

        val shipments: List<Shipment>? = fftService.getShipmentsForPickjob(pickJobId = packJobCreatedEvent.payload.pickJobRef)
        if (shipments.isNullOrEmpty()) {
            logger.info { "No shipment found for Pickjob ${packJobCreatedEvent.payload.pickJobRef} - Aborting." }
            return@run
        }

        val shipment: Shipment = shipments.first()
        if (packJobCreatedEvent.event == "PACK_JOB_CREATED" &&
            shipment.sourceAddress != null &&
            shipment.targetAddress != null &&
            shipment.sourceAddress.phoneNumbers.isNotEmpty() &&
            shipment.targetAddress.phoneNumbers.isNotEmpty()
        ) {
            logger.info { "Processing PACK_JOB_CREATED Event from fulfillmenttools..." }

            val parcel: Parcel = fftService.createProcessingParcel(shipment) ?: return@run

            val sourceAddress = shipment.sourceAddress
            val targetAddress = shipment.targetAddress

            //the UberService implementation puts shipment & parcelId to the created delivery at Uber for later use
            val createdDelivery : CreatedDelivery? = uberService.createDelivery(
                ...
            )

            if (createdDelivery == null) {
                logger.error { "Failed to create delivery." }
                return@run
            }

            val labelBase64 = pdfService.createLabel(
                    ...
            )

            if (parcel.documentsRef == null) {
                logger.error { "No documentsRef found on Parcel." }
                return@run
            }

            val document = fftService.uploadLabel(packJobCreatedEvent.payload.documentsRef,labelBase64)
            if (document == null) {
                logger.error { "No label could be created." }
                return@run
            }

            fftService.setParcelToDone(parcel, createdDelivery, document.id)
        } else {
            logger.error { "Missing parameters in callback. Aborting." }
            return@run
        }
    }
    /**
     * Called from Uber for delivery tracking updates
     */
    @PostMapping("/deliveryStatusCallback")
    suspend fun deliveryStatusCallback(@RequestBody deliveryStatusEvent: DeliveryStatusEvent) = run {
        if (deliveryStatusEvent.status != "pickup_complete") {
            logger.info { "Discarding Uber Event: ${deliveryStatusEvent.status}. Processing stopped." }
            return@run
        }
        logger.info { "Trigger Event ${deliveryStatusEvent.status} received from Uber Direct: ${Gson().toJson(deliveryStatusEvent)}" }

        val ids: List<String> = deliveryStatusEvent.data.external_id?.split("####") ?: emptyList()
        if (ids.size != 2) {
            logger.error { "Wrong count (${ids.size}) of params in Uber external_id." }
            return@run
        }

        val shipmentId: String = ids[0]
        val parcelId: String = ids[1]
        val handoverJob = fftService.getHandoverForParcelInShipment(parcelId,shipmentId)
        if(handoverJob == null){
            throw Exception("No HandoverJob found for Parcel $parcelId after 5 retries!")
        }
        fftService.setHandoverToHandedOver(handoverJob)

        logger.info { "Process completed SUCCESSFULLY for Delivery ${deliveryStatusEvent.id}. Done." }
    }

Deploy the service to Google Cloud Run

Issuing the command gcloud run deploy headlesscarrierservice in the console triggers the deployment of the service from its source code. After the build completes, the container is available at its assigned URL, for instance: https://headlesscarrierservice-558061097749.europe-west1.run.app.

This host URL is required for the remaining configuration steps in fulfillmenttools and Uber.

Create a fulfillmenttools subscription

To connect the service to a fulfillmenttools instance, create an HTTP subscription for the desired event. This is done by issuing the following API call, as detailed in the eventing documentation:

curl --location 'https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/subscriptions/' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: ••••••' \
      --data '{
          "callbackUrl": "https://headlesscarrierservice-558061097748.europe-west1.run.app/requestPickupCallback",
          "event": "PACK_JOB_CREATED",
          "headers": [
              {
                  "key": "Content-Type",
                  "value": "application/json"
              }
          ],
          "name": "Uber Carrier Connector Service - Request Pickup after Picking Completed"
      }'
< 201 Created
{
    "callbackUrl": "https://headlesscarrierservice-558061097748.europe-west1.run.app/requestPickupCallback",
    "event": "PACK_JOB_CREATED",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json"
        }
    ],
    "name": "Uber Carrier Connector Service - Request Pickup after Picking Completed",
    "lastModified": "2024-09-24T09:27:53.833Z",
    "id": "b0eee1d0-ae92-4723-8a67-e73ef60d7ac7",
    "created": "2024-09-24T09:27:53.833Z"
}

From this point on, every PACK_JOB_CREATED event within fulfillmenttools will be received and processed by the created service.

Configuration of Uber

Uber offers a webhook mechanism similar to the subscription pattern in fulfillmenttools. A connection from Uber to the created service can be established by creating a webhook for event.delivery_status events in the Uber developer dashboard (example UI shown in German):

Ensure that the correct service URL and endpoint are used. Once saved, Uber will send tracking events to the specified endpoint, where they will be handled by the service.

When an order is processed in the configured facility, this mechanism will trigger the creation of the delivery, upload a self-generated PDF to fulfillmenttools, and process the track-and-trace events.

In this article, we'll describe the end-to-end integration flow for custom carriers with external label creation and tracking updates, and how you can implement this. The flow applies to carriers that are configured with external label creation enabled.

Prerequisites

• A custom carrier has been created with a key starting with CUSTOM_

• A webhook endpoint is configured to receive HTTP POST callbacks for parcel events

• The integration layer is capable of generating shipping labels and tracking information via the carrier system

For more information, see the Configuration of fulfillmenttools section in the Custom carrier article.

Below is the visual representation of the custom carrier integration flow:

Once an order is created, the process begins. To set up a custom carrier to follow this flow, follow the steps below.

Operational processes and client-specific behavior aren't included in this article.

1

Connect the custom carrier to the facility

Use the endpoint below to connect the carrier to the facility.

POST https://{YOUT_TENANT_NAME}.api.fulfillmenttools.com/api/facilities/{facilityId}/carriers/{carrierRef}

Example request

Create a carrier facility connection

{
    "status": "ACTIVE",
    "configuration": {
      "manualParcelHandlingActive": true
    }
  }

Example response

After an order is processed and packed at the facility, a parcel is created in fulfillmenttools. If manualParcelHandlingActive is set to true for the facility carrier connection, the parcel is created with status PROCESSING, and the event PARCEL_CARRIER_REQUESTED is emitted. This event indicates that the integration layer is responsible for label creation.

If manualParcelHandlingActive is set to false, the parcel is created with status DONE without a label.

The emitted event contains, among others:

• The parcel identifier

• Carrier reference and carrier key

• Delivery address information

• Parcel dimensions and item information

PARCEL_CARRIER_REQUESTED indicates that the integration layer must create labels and update the parcel.

2

Receive parcel creation events for external label generation

Based on the received parcel information, the integration layer creates the shipment in the carrier system.

The integration layer obtains the required label and tracking data from the carrier system and provides it to fulfillmenttools.

For the ADD_LABELS_TO_PARCEL action, the following data is required for sendLabel:

• File

  • content as a base64-encoded PDF

  • type with value PDF

• type either SEND_LABEL or RETURN_LABEL

• trackingNumber

• trackingUrl as a fully qualified URL

Optionally, the same structure can be provided for returnLabel. If required, a customsDocument can be provided as a base64-encoded PDF.

3

Inject the shipping and return labels into parcels

After the integration layer has generated the required label and tracking data, the parcel is updated using the ADD_LABELS_TO_PARCEL action.

As part of the label injection, an optional tenantParcelId can be provided to reference the parcel in external systems.

If the label injection is successful and closeParcel is set to true, the parcel is closed and becomes eligible for handover processing.

POST https://{YOUT_TENANT_NAME}.api.fulfillmenttools.com/api/parcels/{parcelId}/actions

Example request (shipping and return label, and optional customs document)

{
    "version": 1,
    "name": "ADD_LABELS_TO_PARCEL",
    "tenantParcelId": "{{tenantParcelId}}", //a parcel Id that can be freely selected
    "closeParcel": true,
    "labels": [
      {
        "labelType": "SEND_LABEL",
        "labelFile": {
          "content": "{{sendLabel}}",
          "type": "PDF"
        },
        "trackingNumber": "1b6da28d-5a48-40eb-9ad2-5307b58db10d",
        "trackingUrl": "https://track.example.com/1b6da28d-5a48-40eb-9ad2-5307b58db10d"
      },
      {
        "labelType": "RETURN_LABEL",
        "labelFile": {
          "content": "{{returnLabel}}",
          "type": "PDF"
        },
        "trackingNumber": "7d7ea081-71ec-4f68-b010-7c1d5527a22c",
        "trackingUrl": "https://track.example.com/7d7ea081-71ec-4f68-b010-7c1d5527a22c"
      },
    ],
    
    "customsDocument": {
      "labelFile": {
        "content": "{{customsDoc}}",
        "type": "PDF"
      }
    }
  }

Example response (simplified)

We also recommend adding error handling at this stage using the same endpoint.

If label creation fails in the integration layer, the ADD_LABELS_TO_PARCEL action can be used to persist the error state. Error information is provided per label via sendLabel and returnLabel, using errorDescription and an optional errorCode. This allows fulfillmenttools to reflect the error state without attaching label content.

Example request (error case)

{
    "version": 1,
    "name": "ADD_LABELS_TO_PARCEL",
    "labels": [
      {
        "type": "SEND_LABEL",
        "errorDescription": "Human-readable send error description",
        "errorCode": "Optional send error code"
      },
      {
        "type": "RETURN_LABEL",
        "errorDescription": "Human-readable return error description",
        "errorCode": "Optional return error code"
      }
    ],
  }

Example response (simplified)

4

Update tracking data during the shipment lifecycle

After labels have been attached, tracking data can be updated during the shipment lifecycle.

Tracking updates are applied using the UPDATE_TRACKING_DATA action. The action supports updates for SEND_LABEL and RETURN_LABEL independently.

Each update can include status, an optional carrierStatus, and trackingNumber. Multiple updates can be applied over time to reflect shipment progress until the parcel reaches the end customer.

Tracking data updates can reference a parcel either by its parcelID or by a tenantParcelId. Both options use the same parcel actions endpoint. The distinction is made via the URL, while the request body and response remain unchanged.

Parcel ID endpoint

POST https://{YOUT_TENANT_NAME}.api.fulfillmenttools.com/api/parcels/{parcelId}/actions

Tenant parcel ID endpoint

POST https://{YOUT_TENANT_NAME}.api.fulfillmenttools.com/api/parcels/urn:fft:parcel:tenantParcelId:{tenantParcelId}/actions

Example request

{
    "version": 2,
    "name": "UPDATE_TRACKING_DATA",
    "trackingData": [
      {
        "type": "SEND_LABEL",
        "status": "PICKED_UP",
        "carrierStatus": "Optional free text",
        "trackingNumber": "74224272-962b-467d-b44a-07a85ff9479c"
      }
    ]
  }

Example response (simplified)