Carrier configuration

What is a carrier?

Inside the fulfillmenttools platform, a carrier is an entity enabling you to connect Courier, Express, and Parcel services (in short CEP services). If your favorite provider isn't yet listed, let us know using our feedback form.

Adding the first carrier

This tutorial uses a sample company, LU.XY, which uses two carriers for fulfilling orders: DHL for domestic orders within Germany and UPS for all other orders. The first step is to add DHL as a carrier. For this example, a default parcel weight of 2000 grams is assumed, which corresponds to the API field defaultParcelWeightInGram.

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/carriers

{
  "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 specifies the carrier to add; refer to the list of available carriers for the correct key value. The name can be defined freely. The status can be set to either ACTIVE or INACTIVE. If a carrier is created with an ACTIVE status, it is immediately available for use. If defaultParcelWeightInGram is set, labels are created with that weight. The credentials are provided by the carrier.

A successful request returns a 201 CREATED response. The response body contains the unique ID assigned to the new carrier.

Next, create the UPS carrier. The same API endpoint is used, but with a different payload:

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/carriers

{
  "key": "UPS",
  "name": "LU.XY UPS account",
  "status": "ACTIVE",
  "credentials": {
    "key": "UPS",
    "user": "VCE_worldwide_username",
    "password": "VCE_password"
  }
}

Note that the user and password values in this example are prefixed with VCE. VCE is a technology partner that enables fulfillmenttools to provide an expedited integration for some CEP service providers. The professional services representative provides the necessary credentials for this partner.

Connect a facility to a carrier

After the carriers are created in the fulfillmenttools platform, a connection must be established between a facility and each carrier. This connection is necessary for reasons such as contractual agreements or country-specific carrier availability.

This is done by an easy API call to the endpoint for facility carrier connections. In our case, an empty JSON for the payload is good here:

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/facilities/{facilityId}/carriers/{carrierId}

{}

This call requires the carrierId from the previous step and the facilityId from when the facility was created. A successful request returns a 200 OK response with the new connection details:

200 OK response

{
    "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"
}

The connection is created with an INACTIVE status. To activate it, send a PUT request to the same endpoint:

PUT https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/facilities/{facilityId}/carriers/{carrierId}

{
    "version": 1,
    "status": "ACTIVE",
    "name": "UPS"
}

Note that the payload includes the version number (1) from the previous response. It is crucial to provide the current version of the resource when making updates to prevent conflicts.

200 OK response

{
    "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"
}

Repeat this process to connect and activate all other required carriers for the facility.