OnTrac REST API: Labels, Rates, Tracking and Address Validation

OnTrac runs two APIs. The legacy XML API on shipontrac.net is the ontrac carrier and authenticates with a numeric account number and password. The newer OnTrac WS V3 JSON API on ws.ontrac.com, introduced after the LaserShip merger, is the ontrac-rest carrier described on this page. New OnTrac integrations and LaserShip migrations are set up on V3.

Credentials#

OnTrac emails a WSID and WSKey when web services are enabled on your account, along with one or more eight-character CustomerBranch codes, one per shipping warehouse. There is no OAuth step: the credentials are static and travel in every request.

The same values can come from the environment as RS_ONTRAC_REST_USERNAME, RS_ONTRAC_REST_PASSWORD and RS_ONTRAC_REST_ACCOUNT_NUMBER. Both secrets are redacted from meta.debug_information.

Test mode#

OnTrac has no sandbox host. Setting "test": true sets the Test flag on submitshipment and voidshipment, so the order is validated and answered with real-looking barcodes and labels but never processed or billed. getallrates, track and addressvalidate have no test flag and always run against the live service. Tracking a test barcode returns OnTrac's sample tracking history.

Supported actions#

Pickups, manifests and time in transit are not part of the V3 API. Delivery estimates come back with each rate.

Creating a label#

Every piece needs a non-zero weight, non-zero length, width and height, and a description. OnTrac accepts pounds or grams and inches or centimeters; weight_unit values of KG and OZ are converted for you.

{
  "carrier": "OnTrac-REST",
  "action": "submitshipment",
  "params": {
    "username": "YOUR_WSID",
    "password": "YOUR_WSKEY",
    "account_number": "YOUR_CUSTOMER_BRANCH",
    "test": true,
    "service": "GRND",
    "image_type": "rs_zpl",
    "po_number": "ORDER-1001",
    "shipper": "RocketShipIt",
    "ship_contact": "Warehouse Manager",
    "ship_addr1": "7400 W Buckeye Rd",
    "ship_city": "Phoenix",
    "ship_state": "AZ",
    "ship_code": "85043",
    "ship_phone": "6025551234",
    "to_name": "Jane Doe",
    "to_addr1": "132 N F St",
    "to_city": "Lake Worth",
    "to_state": "FL",
    "to_code": "33460",
    "to_phone": "7037619031",
    "packages": [
      { "weight": 2.5, "length": 10, "width": 8, "height": 4, "description": "Groceries" }
    ]
  }
}

Parameter mapping#

OnTrac requires the contact name to differ from the company name at each address. Business destinations must carry a to_company; a destination without one is treated as residential.

Services#

Additional codes returned by getallrates are passed through as-is.

Piece attributes#

Set attributes to a list of OnTrac attribute names to apply them to every piece: ControlledSubstance, Alcohol, DryIce, Refrigerated, Hazmat, Explosive, TwoPersons, Perishable, NoRTS, DesktopDelivery, SignatureRequired, Saturday, Sunday.

Existing RocketShipIt flags map onto them as well: any signature_type other than NONE adds SignatureRequired; packages[].alcohol, dry_ice and hazmat add Alcohol, DryIce and Hazmat (the first and last also add SignatureRequired, as OnTrac requires); saturday_delivery adds Saturday.

NoRTS tells OnTrac to document and destroy undeliverable pieces instead of returning them, which is the only case where a return address is optional.

Labels#

OnTrac returns one label per piece inside a single blob. ZPL labels are split so each entry in packages carries its own label. A PDF is one multi-page file and is attached to the first package. Orders with more than one piece also list the combined blob under documents with the code labels.

Rates#

getallrates returns one rate per service OnTrac can offer for the order, with est_delivery_time set from OnTrac's expected delivery and rate_detail listing each charge code (see Rate Details). The rate request uses the same parameters as a label; the recipient contact and shipper details are optional. CustomerBranches ending in PKUP also need ship_code, which is sent as the injection postal code.

Tracking#

Only shipments placed through the V3 API can be tracked with it. Pass one tracking_number or several in tracking_numbers. Events are returned most recent first with OnTrac's event type in status_code (for example Delivered, Departed, Received) and the modifier in status_type (DLVD, OFDL). A Delivered event fills delivered_time and delivery_detail.

Voiding#

voidshipment cancels each tracking_number. OnTrac accepts the cancel until the piece is loaded for delivery; after that it answers with the ToLate error.

Errors#

OnTrac reports validation failures as a list of field names such as DeliverTo-PostalCode or Pieces-0-Weight. RocketShipIt returns one error per field and names the RocketShipIt parameter to fix:

"errors": [
  { "code": "DeliverTo-PostalCode", "description": "DeliverTo.PostalCode failed validation (to_code)", "type": "Error" },
  { "code": "Pieces-0-Weight", "description": "Pieces.0.Weight failed validation (packages[0].weight)", "type": "Error" }
]