Customizing RocketShipIt Requests

RocketShipIt comes with an experimental feature to allow you to customize the requests that are sent to the shipping carriers. Most RocketShipIt users will not need this feature. It is intended as an escape hatch for users who need to customize the requests for:

• Adding new carrier features before RocketShipIt can support them officially
• Debugging carrier issues
• Special integrations
• Non-standard API requirements

If you find yourself needing this feature, please contact us and let us know how you're using it. If it is a common use case, we may add support for it in the RocketShipIt core product.

Currently supported carriers:

• UPS
• Other carriers coming soon (early 2025)

How it works

If the parameter transform_request_js is included in the request, RocketShipIt will transform the request using the provided JavaScript code.

The JavaScript code has access to the following variables/functions:

• requestBody - The original request body created by RocketShipIt that would otherwise be sent to the carrier
• setJSON(jsonString, jsonPath, value) - Sets the value of a key in an object. jsonPath is sjson syntax
• setRequestBody(body) - Sets the request body to the provided value
• setHeader(key, value) - Sets the value of an HTTP header
• console.log(message) - Causes a RocketShipIt error to be returned which includes all console.log output

The JavaScript code has access to the request body, which you can read and modify in the requestBody variable.

Examples

For example, lets say you wanted to set a custom user agent string for the UPS Label Recovery API. This is something RocketShipIt doesn't normally support.

The JavaScript code would look like this:

// The original RocketShipIt request is in requestBody.
// It is good practice to copy it to retain an original copy
newBody = requestBody;
// We set the user agent to "test" given the JSON path to the user agent field
newBody = setJSON(newBody, 'LabelRecoveryRequest.LabelSpecification.HTTPUserAgent', 'test');
// We set the modified request as the new request body that we want to send to the carrier.
// This is the most important line. Nothing significant happens until this is called.
setRequestBody(newBody);

Full RocketShipIt JSON request:

{
  "carrier": "UPS-REST",
  "action": "LabelRecovery",
  "params": {
    "transform_request_js": "newBody = requestBody;newBody = setJSON(newBody, 'LabelRecoveryRequest.LabelSpecification.HTTPUserAgent', 'test');setRequestBody(newBody);",
    "tracking_number": "1Z12345E8791315413",
    "test": true
  }
}

This will produce a request that looks like this:

{
  "LabelRecoveryRequest": {
    "LabelDelivery": {
      "LabelLinkIndicator": "",
      "ResendEmailIndicator": ""
    },
    "LabelSpecification": {
      "HTTPUserAgent": "test", // we changed this
      "LabelImageFormat": {
        "Code": "ZPL"
      },
      "LabelStockSize": {
        "Height": "6",
        "Width": "4"
      }
    },
    "Request": {
      "RequestOption": "Non_Validate",
      "SubVersion": "1903",
      "TransactionReference": {
        "CustomerContext": "",
        "TransactionIdentifier": ""
      }
    },
    "TrackingNumber": "1Z12345E8791315413",
    "Translate": {
      "Code": "01",
      "DialectCode": "US",
      "LanguageCode": "eng"
    }
  }
}