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 Mickey and Minnie super fast, and we want to use Priority Mail Express™.

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

Example

POST /v1/labels/

curl -iX POST https://api.shipengine.com/v1/labels \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
{
  "shipment": {
    "carrier_id": "se-123890",
    "service_code": "usps_priority_mail_express",
    "ship_to": {
      "name": "Mickey and Minnie Mouse",
      "phone": "714-781-4565",
      "company_name": "The Walt Disney Company",
      "address_line1": "500 South Buena Vista Street",
      "city_locality": "Burbank",
      "state_province": "CA",
      "postal_code": "91521",
      "country_code": "US",
      "address_residential_indicator": "no"
    },
    "ship_from": {
      "name": "Dade Murphy",
      "phone": "512-485-4282",
      "company_name": "Zero Cool",
      "address_line1": "345 Chambers Street",
      "address_line2": "Suite 100",
      "city_locality": "New York City",
      "state_province": "NY",
      "postal_code": "10282",
      "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
}