About label test mode

In order to enable you to be able to get labels back and validate them or to be able to validate that the software you're building is using the responses correctly, Shipium's APIs provide a test mode 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.

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

Setting "testMode": true in your API calls is recommended whenever you are doing any kind of integration testing with Shipium Carrier and Method Selection. The following table demonstrates the expected behavior when using test mode.

Request	Carrier method in test mode	Carrier method NOT in test mode
`"testMode": true`	Carrier 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're getting them initially configured and until you're ready to start shipping with that carrier. During the setup 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 in the Test for a New Carrier section below.

Test mode API calls

Specify test mode in the all-in-one service and carrier method and shipping label call

The following is an example of using test mode with the all-in-one Carrier and Method Selection & Shipment Label API call. The testMode field is set to a value of "true" and included in the shipment parameters of the call.

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

Test for a new carrier

If you're trying to test a newly added carrier, you'll 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 Specify Carrier Service and Method and then force the carrier and method in question by finding the value in the Supported Carriers document.

Note that you can specify more than one carrier and method if you're 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 Carrier and Method Selection & Shipment Label API call.

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

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful: