Understanding Carrier Selection Label Test Mode

Test Mode Overview

In order to enable you to be able to get labels back and validate them or to be able to validate that the software that you are building is using the responses correctly, our APIs provide a testMode to allow you to make calls without causing you to be charged for those calls by the carriers.

Test mode can be specified either in an individual API call or by setting a given carrier method for a particular carrier account in test mode via the Shipium console application.

Setting carrier methods to test mode in the console is recommended when first implementing Shipium Carrier Selection or when adding a new carrier method after you are already in production.

Setting "testMode": true in your API calls is recommended whenever you are doing any kind of integration testing with Shipium Carrier Selection.

Test Mode Overview Table

RequestCarrier Method in Test ModeCarrier Method NOT in Test Mode
"testMode": trueCarrier Method is considered for selection and a testMode request is made.Carrier Method is considered for selection and a testMode request is made
"testMode": false OR "testMode" not passed.Carrier Method is not considered for selection.Carrier Method is considered and makes a production (i.e. charging) request.

Test Mode Details

Carrier Methods in Test Mode

When you initially set up a new carrier and a set of methods (or a new method for a carrier), you will want to set them up in test mode while you are getting them initially configured and until you are ready to start shipping with that carrier. During the set-up process of a new carrier, you can mark it in testMode and then remove test mode when your testing is complete.

To explicitly test the new carriers and methods, see the API example under "Testing for a new Carrier" below.

Test Mode API Calls

Specifying Test Mode in the All-in-One Call

Below you will see an example of using testMode with the all-in-one label call.

{
  "currencyCode": "usd",
  "generateLabel": true,
  "labelParameters": {
    "testMode": true,
    "currencyCode": "usd",
    "labelFormats": [
      "ZPL"
    ],
    "manifest": true,
    "includeLabelImagesInResponse": true
  },
  ...
}

Testing for a new Carrier

If you are trying to test a newly added carrier, you will want to force it to be selected to make testing simpler. To get details on forcing a particular carrier, you can look at the full documentation under Specifying Carrier Service and Method and then force the carrier and method in question by finding the value in Supported Carriers.

Note that you can specify more than one carrier and method if you are trying to test specific use cases, though for the testing discussed here, it would likely be only a single carrier and method.

Here is a partial example with the relevant pieces of the API call for the All-in-One call.

{
  "currencyCode": "usd",
  "generateLabel": true,
  "labelParameters": {
    "testMode": true,
    "currencyCode": "usd",
    "labelFormats": [
      "ZPL"
    ],
    "manifest": true,
    "includeLabelImagesInResponse": true
  },
  ...
  "shipmentParameters": {
    ...
  },
  ...
  "carrierServiceMethodAllowList": [
    "usps-first-class-package-service-method",
    "ups-ground-service-method"
  ],
  ...
}