Creation Modes

Sometimes sending data to Carrier Connect doesn't work out as expected: e.g. the zip code is incorrect, the carrier doesn't allow to ship packages with these dimensions or not all required data is available.

These and many more validations are performed every time new shipments, packages, items, etc. are to be created.

Carrier Connect allows you to choose between various creation modes, which determine the behavior for data creation and error handling.

Creation mode "ALWAYS": Shipment and packages are created, even if validation fails

The shipment and packages are created even if validation fails and validation warnings are returned.

It is possible to configure Carrier Connect to respond with an "error label", which contains the error and/or warnings. This helps also to at least have "something" to be printed even if the real carrier label could not be created.

The errors can then be corrected

• either manually using the Carrier Connect UI (attention: there will probably be a system inconsistency between Carrier Connect and the sending ERP / WMS system)
• in the sending system (ERP / WMS system). Then the shipment has to be canceled via the cancelShipment API call and retransmitted with a createShipment call. The cancellation step is necessary because a direct retransmission of existing shipments and packages is not allowed.

... 
"creationParms": {
    "creationMode": "ALWAYS"
  },
...

<creationParms>
	<creationMode>ALWAYS</creationMode>
</creationParms>

Creation mode "VALIDATION_OK": Shipments and packages are only created, if the shipment could be successfully validated

The shipments, packages, or items are only created if the shipment could be successfully validated. Otherwise, validation warnings will be returned in the response. A direct retransmission, after reviewing the data, is possible since no data has been created by the initial call.

... 
"creationParms": {
    "creationMode": "VALIDATION_OK"
  },
...

<creationParms>
	<creationMode>VALIDATION_OK</creationMode>
</creationParms>

📘

What is common use?

Most customers prefer the "VALIDATION_OK" mode.

Error handling

If errors or warnings occur, the API response will always have header information indicating the type (error, retryable error, and/or warnings) and contains the related messages.

{
  "hasErrors": true,
  "hasOnlyRetryableErrors": false,
  "hasWarnings": false,
  "messages": [
    {
      "messageType": "ERROR",
      "messageIdentCode": "PICKUP_NOT_FOUND_ERROR",
      "messageTexts": [
        {
          "languageISOCode": "en",
          "text": "Unable to find pickup for Pickup no. ..."
        }
      ],
      "indentationLevel": 0
    }
  ]
}

<hasErrors>true</hasErrors>
<hasOnlyRetryableErrors>false</hasOnlyRetryableErrors>
<hasWarnings>false</hasWarnings>
<messages>
	<messageType>ERROR</messageType>
	<messageIdentCode>PICKUP_NOT_FOUND_ERROR</messageIdentCode>
	<messageTexts>
		<languageISOCode>en</languageISOCode>
		<text>Unable to find pickup for Pickup no. ...</text>
	</messageTexts>
	<indentationLevel>0</indentationLevel>
</messages>

hasErrors

An error is returned if the operation couldn't be performed because of a basic issue (non-unique transactionIds or if data cannot be found in the system, as in the example above). The shipment won't be created.

hasOnlyRetryableErrors

If all errors are retryable errors, e.g. some data was locked, this is indicated.

hasWarnings

A warning is returned if if the operation couldn't be performed because there is for example a missing field, a wrong postal code or the chosen carrier service is not available for the consignee. Usually the shipment will be created, but no labels (if requested) will be printed.

Note: At the moment, the indentationLevel is not used. It is always "0".

❗️

Be aware that no shipment will be created on a createShipment if you are using the following parameter combination:

• doCompletion = true &&
• creationMode = VALIDATION_OK

And getting back only warnings:

• hasErrors = false &&
• hasWarnings = true

Since a shipment can't be closed/completed (doCompletion = true) without the necessary label documents being created, in this special case you have to handle the warnings as if they where errors.