Use a Carrier Service

tip

Requirements

  • You'll be expected to be familiar with carriers and services.
  • You will need to know how to List Your Carriers; you will need the carrier_id or carrier_code you intend to use for this call.
  • You will need to know how to List Carrier Services; you will need the service_code you intend to use for this call.

While we technically covered this in Quickstart: Create a Label we didn't break out and explain what was happening.

When creating a label, a few things can happen where we figure out how you want to ship.

info

Specifying a Shipment Type

First, we'll need to know which carrier you're using; this is passed to ShipEngine as the carrier_id. Next, you'll want to pass the service_code to select the particular offering for this shipment.

We'll expand and highlight the changes we made to the request body from the Quickstart. Let's say we really need to get this package to it's destination quickly, so we want to use Priority Mail Express™.

We can use the service_code provided in the carrier services list.

Example

POST /v1/labels/

POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
  "shipment": {
    "carrier_id": "se-123890",
    "service_code": "usps_priority_mail_express",
    "ship_to": {
      "name": "Amanda Miller",
      "phone": "555-555-5555",
      "address_line1": "525 S Winchester Blvd",
      "city_locality": "San Jose",
      "state_province": "CA",
      "postal_code": "95128",
      "country_code": "US",
      "address_residential_indicator": "yes"
    },
    "ship_from": {
      "company_name": "Example Corp.",
      "name": "John Doe",
      "phone": "111-111-1111",
      "address_line1": "4009 Marathon Blvd",
      "address_line2": "Suite 300",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78756",
      "country_code": "US",
      "address_residential_indicator": "no"
    },
    "packages": [
      {
        "weight": {
          "value": 9.6,
          "unit": "ounce"
        },
        "dimensions": {
          "unit": "inch",
          "length": 12.0,
          "width": 7.1,
          "height": 6.0
        }
      }
    ]
  }
}

Notice we had already included a service_code in the Quickstart example. We changed that to another service that corresponds with our carrier_id.

{
  "carrier_id": "se-123890",
  "service_code": "usps_priority_mail_express"
}

{
  "label_id": "se-test-202923025",
  "status": "processing",
  "shipment_id": "se-202923025",
  "ship_date": "2019-07-25T05:00:00.000Z",
  "created_at": "2019-07-25T15:24:46.657Z",
  "shipment_cost": {
    "currency": "usd",
    "amount": 0.0
  },
  "insurance_cost": {
    "currency": "usd",
    "amount": 0.0
  },
  "tracking_number": "9999999999999",
  "is_return_label": false,
  "is_international": false,
  "batch_id": "",
  "carrier_id": "se-0",
  "service_code": "usps_priority_mail_express",
  "package_code": "package",
  "voided": false,
  "label_format": "pdf",
  "label_layout": "4x6",
  "trackable": false,
  "carrier_code": "stamps_com",
  "tracking_status": "unknown",
  "label_download": {
    "pdf": "https://api.shipengine.com/v1/downloads/6/Q2OLdnGaqk-UzkN6pFH0lg/testlabel-202923521.pdf",
    "png": "https://api.shipengine.com/v1/downloads/6/Q2OLdnGaqk-UzkN6pFH0lg/testlabel-202923521.png",
    "zpl": "https://api.shipengine.com/v1/downloads/6/Q2OLdnGaqk-UzkN6pFH0lg/testlabel-202923521.zpl",
    "href": "https://api.shipengine.com/v1/downloads/6/Q2OLdnGaqk-UzkN6pFH0lg/testlabel-202923521.pdf"
  },
  "form_download": null,
  "insurance_claim": null
}