Introduction to carrier configuration

This guide demonstrates how to configure carriers and connect them to facilities via the REST API.

Adding the first carrier

The first step is to add the required carriers to the tenant. The following example shows how to add a DHL carrier, assuming a default parcel weight of 2 kilograms.

A new carrier is added by sending a POST request to the carrier endpoint.

curl --location 'https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/carriers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
  "key": "DHL_V2",
  "name": "LU.XY services DHL account",
  "status": "ACTIVE",
  "defaultParcelWeightInGram": 2000,
  "credentials": {
    "key": "DHL_V2",
    "apiKey": "myApiKey",
    "fallback": {
      "key": "DHL_V2",
      "billingNumber": "123456",
      "retoureBillingNumber": "optional123345",
      "dhlBusinessPassword": "mycoolandsecretpw",
      "dhlBusinessUsername": "mycreativeusername"
    }
  }
}'

The key property defines the specific carrier to add. The name can be defined freely. The status can be either ACTIVE or INACTIVE. If a carrier is created with an ACTIVE status, it is immediately available for use. Setting the defaultParcelWeightInGram to 2000 causes labels to be generated with that weight by default. The credentials are provided by the carrier.

A successful request returns a 201 Created response containing the ID of the new carrier.

After creating the DHL carrier, the same process is used to add UPS. The API endpoint is identical, but the payload is different:

curl --location 'https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/carriers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
    "key": "UPS",
    "name": "LU.XY UPS account",
    "status": "ACTIVE",
    "credentials": {
        "key": "UPS",
        "user": "VCE_worldwide_username",
        "password": "VCE_password"
    }
}'

The user and password credentials in this example are prefixed with "VCE". VCE is a technology partner that enables fulfillmenttools to provide integrations with certain Courier, Express, and Parcel (CEP) service providers more quickly. The credentials for this technology partner are provided by a professional services representative.

Connect a facility to a carrier

After carriers are created in the fulfillmenttools platform, they must be connected to a facility. This is necessary for various reasons, such as contractual requirements or because a specific carrier is not supported in a facility's country.

A connection is established with a POST request to the endpoint for facility-carrier connections. For a basic connection, an empty JSON object is sufficient for the payload.

curl --location 'https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/facilities/<YOUR-FACILITY-ID>/carriers/<YOUR-CARRIER-ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{ }'

This request requires the id of the previously created carrier and the id of the target facility. A successful connection returns a 200 OK response with a payload similar to this:

{
    "version": 1,
    "name": "UPS",
    "status": "INACTIVE",
    "cutoffTime": {
        "hour": 12,
        "minute": 0
    },
    "carrierRef": "77214fbf-415c-407b-a682-0fa901ed7848",
    "key": "UPS",
    "deliveryType": "DELIVERY",
    "deliveryAreas": [],
    "facilityRef": "946f17d0-2d14-48f0-a912-d358f2c70e8f",
    "id": "946f17d0-2d14-48f0-a912-d358f2c70e8f_77214fbf-415c-407b-a682-0fa901ed7848",
    "created": "2024-01-24T09:19:44.048Z",
    "lastModified": "2024-01-24T09:19:44.048Z"
}

To activate the connection, send a PUT request to the same endpoint.

curl --location --request PUT 'https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/facilities/<YOUR-FACILITY-ID>/carriers/<YOUR-CARRIER-ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
    "version": 1,
    "status": "ACTIVE",
    "name": "UPS"
}'

It is crucial to include the version number from the object received in the previous GET or POST response. A successful activation returns a 200 OK response with the updated object:

{
    "version": 3,
    "name": "UPS",
    "status": "ACTIVE",
    "cutoffTime": {
        "hour": 12,
        "minute": 0
    },
    "carrierRef": "77214fbf-415c-407b-a682-0fa901ed7848",
    "key": "UPS",
    "deliveryType": "DELIVERY",
    "deliveryAreas": [],
    "facilityRef": "946f17d0-2d14-48f0-a912-d358f2c70e8f",
    "id": "946f17d0-2d14-48f0-a912-d358f2c70e8f_77214fbf-415c-407b-a682-0fa901ed7848",
    "configuration": null,
    "parcelLabelClassifications": null,
    "tags": null,
    "created": "2024-01-24T09:19:44.048Z",
    "lastModified": "2024-01-24T13:47:48.324Z"
}

This process can be repeated for all required facility-carrier connections.