# About label test mode

In order to enable you to get labels back and validate them or 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](https://partner.shipium.com/login).

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](https://docs.shipium.com/docs/label-test-mode#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](https://docs.shipium.com/docs/carrier-and-method-selection-and-shipment-label-api) call. The `testMode` field is set to a value of "true" and included in the shipment parameters of the call.

```json
{
  "currencyCode": "usd",
  "generateLabel": true,
  "labelParameters": {
    "currencyCode": "usd",
    "labelFormats": [
      "zpl"
    ],
    "eligibleForManifest": 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](https://docs.shipium.com/docs/specifying-carrier-service-and-method) and then force the carrier and method in question by finding the value in the [Supported Carriers](https://docs.shipium.com/docs/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](https://docs.shipium.com/docs/carrier-and-method-selection-and-shipment-label-api) call.

```json
{
  "currencyCode": "usd",
  "generateLabel": true,
  "labelParameters": {
    "currencyCode": "usd",
    "labelFormats": [
      "zpl"
    ],
    "eligibleForManifest": 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:

- [Terms and Definitions](https://docs.shipium.com/docs/common-terms)
- [Troubleshooting Guide](https://docs.shipium.com/docs/troubleshooting-guide)
- [Contact Shipium Support](https://docs.shipium.com/docs/contacting-shipium-support)