Custom carrier integration flow

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)