Get a shipping label

Meet Rachael

Rachael is a small e-commerce business owner, www.alltheyarnz.com, who specializes in selling yarn to hobbyists. Until now, she has exclusively used the Shippo web app to manage her shipping. As her business has been growing, she’s looking for ways to become more efficient. She now ships approximately 40,000 packages a year. She needs to integrate Shippo into her workflow to automatically find the best available service levels for her. Looking at her past sales, 10% of the orders have the same weight and size, that means she can use the same size box. She has decided that this is a good place for her to start working with the Shippo API. First, to simplify the process, Rachael creates a parcel object. Because she only uses one parcel size, it makes sense for her to create a parcel object that can be referenced over and over again.

Create parcel request

curl --location 'https://api.goshippo.com/parcels/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "length": 5,
  "width": 5,
  "height": 5,
  "distance_unit": "cm",
  "weight": 2,
  "mass_unit": "lb",
  "template": "",
  "metadata": "Wool Box1"
}'

Create parcel response

{
    "object_state": "VALID",
    "object_created": "2023-07-25T14:41:41.953Z",
    "object_updated": "2023-07-25T14:41:41.953Z",
    "object_id": "d1a39a2feea94decabbf78eb69a91d50",
    "object_owner": "rachael@alltheyarnz.com",
    "template": null,
    "length": "5.0000",
    "width": "5.0000",
    "height": "5.0000",
    "distance_unit": "cm",
    "weight": "2.0000",
    "mass_unit": "lb",
    "value_amount": null,
    "value_currency": null,
    "metadata": "Wool Box1",
    "extra": {},
    "line_items": [],
    "test": true
}

Rachael uses UPS because they’re close to her home. To get shipping rates from her preferred carrier (UPS), she must first find the object ID for that carrier.

Get carrier account request

curl --location 'https://api.goshippo.com/carrier_accounts/?carrier=ups' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json'

Get carrier account response

{
  "carrier": "ups",
  "object_id": "f1f8b350f37c4147a592ac6877743ae4",
  "object_owner": "rachael@alltheyarnz.com",
  "account_id": "shippo_ups_account",
  "parameters": {},
  "test": true,
  "active": true,
  "is_shippo_account": true,
  "metadata": "",
  "carrier_name": "UPS",
  "carrier_images": {
      "75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
      "200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png"
  }
}

Using the object_id from her preferred carrier (UPS) in the carrier_accounts field, Rachael gets rates for her parcel. The response includes rates available to Rachael from only her preferred carrier.

Create shipment request

curl --location 'https://api.goshippo.com/shipments/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "address_from": {
          "name": "Rachael",
          "street1": "1092 Indian Summer Ct",
          "city": "San Jose",
          "state": "CA",
          "zip": "95122",
          "country": "US",
          "phone": "4159876543",
          "email": "rachael@alltheyarnz.com"
  },
  "address_to": {
          "name": "Mr Hippo",
          "street1": "965 Mission St #572",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94103",
          "country": "US",
          "phone": "4151234567",
          "email": "mrhippo@shippo.com"
  },
  "parcels":["d1a39a2feea94decabbf78eb69a91d50"],
  "carrier_accounts":["f1f8b350f37c4147a592ac6877743ae4"],
  "extra": {},
  "async": false
}'

Create shipment response

"carrier_accounts": [
        "f1f8b350f37c4147a592ac6877743ae4"
    ],
    "object_created": "2023-07-25T15:03:57.668Z",
    "object_updated": "2023-07-25T15:03:57.669Z",
    "object_id": "0f26906a9aa54274a56a48e57a1c3338",
    "object_owner": "rachael@alltheyarnsz.com",
    "status": "SUCCESS",
    "address_from": {
        "object_id": "d9795c6cf0de492d9de07a01d243e476",
        "is_complete": true,
        "name": "Rachael",
        "company": "",
        "street_no": "",
        "street1": "1092 Indian Summer Ct",
        "validation_results": {},
        "street2": "",
        "street3": "",
        "city": "San Jose",
        "state": "CA",
        "zip": "95122",
        "country": "US",
        "phone": "4159876543",
        "email": "rachael@alltheyarnz.com",
        "is_residential": null,
        "test": true
    },
    "address_to": {
        "object_id": "db2fb0ee3fb048ac9d00f4b30972410f",
        "is_complete": true,
        "name": "Mr Hippo",
        "company": "",
        "street_no": "",
        "street1": "965 Mission St #572",
        "validation_results": {},
        "street2": "",
        "street3": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94103",
        "country": "US",
        "phone": "4151234567",
        "email": "mrhippo@shippo.com",
        "is_residential": null,
        "test": true
    },
    "parcels": [
        {
            "object_state": "VALID",
            "object_created": "2023-07-25T14:41:41.953Z",
            "object_updated": "2023-07-25T15:03:57.685Z",
            "object_id": "d1a39a2feea94decabbf78eb69a91d50",
            "object_owner": "rachael@alltheyarnz.com",
            "template": null,
            "extra": {},
            "length": "5.0000",
            "width": "5.0000",
            "height": "5.0000",
            "distance_unit": "cm",
            "weight": "2.0000",
            "mass_unit": "lb",
            "value_amount": null,
            "value_currency": null,
            "metadata": "Wool Box1",
            "line_items": [],
            "test": true
        }
    ],
    "shipment_date": "2023-07-25T15:03:57.634Z",
    "address_return": {
        "object_id": "d9795c6cf0de492d9de07a01d243e476",
        "is_complete": true,
        "name": "Rachael",
        "company": "",
        "street_no": "",
        "street1": "1092 Indian Summer Ct",
        "validation_results": {},
        "street2": "",
        "street3": "",
        "city": "San Jose",
        "state": "CA",
        "zip": "95122",
        "country": "US",
        "phone": "4159876543",
        "email": "rachael@alltheyarnz.com",
        "is_residential": null,
        "test": true
    },
    "alternate_address_to": null,
    "customs_declaration": null,
    "extra": {},
    "rates": [
        {
            "object_created": "2023-07-25T15:03:58.496Z",
            "object_id": "90fa81e7dab14a19bd42ca2773482b89",
            "object_owner": "rachael@alltheyarnz.com",
            "shipment": "0f26906a9aa54274a56a48e57a1c3338",
            "attributes": [
                "FASTEST"
            ],
            "amount": "48.11",
            "currency": "USD",
            "amount_local": "48.11",
            "currency_local": "USD",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "Next Day Air® Early",
                "token": "ups_next_day_air_early_am",
                "terms": "",
                "extended_token": "ups_next_day_air_early_am",
                "parent_servicelevel": null
            },
            "estimated_days": 1,
            "arrives_by": "08:30:00",
            "duration_terms": "Next business day delivery by 8:30 a.m., 9:00 a.m., or 9:30 a.m. ",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-25T15:03:58.496Z",
            "object_id": "80362bdfc6364ea8ae542478a12cf206",
            "object_owner": "rachael@alltheyarnz.com",
            "shipment": "0f26906a9aa54274a56a48e57a1c3338",
            "attributes": [],
            "amount": "18.41",
            "currency": "USD",
            "amount_local": "18.41",
            "currency_local": "USD",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "Next Day Air®",
                "token": "ups_next_day_air",
                "terms": "",
                "extended_token": "ups_next_day_air",
                "parent_servicelevel": null
            },
            "estimated_days": 1,
            "arrives_by": "10:30:00",
            "duration_terms": "Next business day delivery by 10:30 a.m., 12:00 noon, or end of day, depending on destination.",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-25T15:03:58.496Z",
            "object_id": "54c1d066fa00401e9ede4111e0519fb2",
            "object_owner": "rachael@alltheyarnz.com",
            "shipment": "0f26906a9aa54274a56a48e57a1c3338",
            "attributes": [],
            "amount": "13.70",
            "currency": "USD",
            "amount_local": "13.70",
            "currency_local": "USD",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "Next Day Air Saver®",
                "token": "ups_next_day_air_saver",
                "terms": "",
                "extended_token": "ups_next_day_air_saver",
                "parent_servicelevel": null
            },
            "estimated_days": 1,
            "arrives_by": "15:00:00",
            "duration_terms": "Next business day delivery by 3:00 or 4:30 p.m. for commercial destinations and by end of day for residentail destinations.",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-25T15:03:58.496Z",
            "object_id": "1d03331062d14b1eb327d178eb68956a",
            "object_owner": "rachael@alltheyarnz.com",
            "shipment": "0f26906a9aa54274a56a48e57a1c3338",
            "attributes": [
                "BESTVALUE",
                "CHEAPEST"
            ],
            "amount": "6.18",
            "currency": "USD",
            "amount_local": "6.18",
            "currency_local": "USD",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "Ground",
                "token": "ups_ground",
                "terms": "",
                "extended_token": "ups_ground",
                "parent_servicelevel": null
            },
            "estimated_days": 1,
            "arrives_by": null,
            "duration_terms": "Delivery times vary. Delivered usually in 1-5 business days.",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-25T15:03:58.496Z",
            "object_id": "2e30da53020f4d349db086fc73be3bc8",
            "object_owner": "rachael@alltheyarnz.com",
            "shipment": "0f26906a9aa54274a56a48e57a1c3338",
            "attributes": [],
            "amount": "10.43",
            "currency": "USD",
            "amount_local": "10.43",
            "currency_local": "USD",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "2nd Day Air® A.M.",
                "token": "ups_second_day_air_am",
                "terms": "",
                "extended_token": "ups_second_day_air_am",
                "parent_servicelevel": null
            },
            "estimated_days": 2,
            "arrives_by": "10:30:00",
            "duration_terms": "Delivery on the second business day by 10:30 a.m. or 12:00 noon to most commercial destinations.",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-25T15:03:58.496Z",
            "object_id": "bdf9cd1ad6714465a134d53cb0307561",
            "object_owner": "rachael@alltheyarnz.com",
            "shipment": "0f26906a9aa54274a56a48e57a1c3338",
            "attributes": [],
            "amount": "9.35",
            "currency": "USD",
            "amount_local": "9.35",
            "currency_local": "USD",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "2nd Day Air®",
                "token": "ups_second_day_air",
                "terms": "",
                "extended_token": "ups_second_day_air",
                "parent_servicelevel": null
            },
            "estimated_days": 2,
            "arrives_by": null,
            "duration_terms": "Delivery by the end of the second business day.",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        },
        {
            "object_created": "2023-07-25T15:03:58.497Z",
            "object_id": "d903683a04014015a803c7e8ce2a9f64",
            "object_owner": "rachael@alltheyarnz.com",
            "shipment": "0f26906a9aa54274a56a48e57a1c3338",
            "attributes": [],
            "amount": "8.92",
            "currency": "USD",
            "amount_local": "8.92",
            "currency_local": "USD",
            "provider": "UPS",
            "provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
            "provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
            "servicelevel": {
                "name": "3 Day Select®",
                "token": "ups_3_day_select",
                "terms": "",
                "extended_token": "ups_3_day_select",
                "parent_servicelevel": null
            },
            "estimated_days": 3,
            "arrives_by": null,
            "duration_terms": "Delivery by the end of the third business day.",
            "messages": [],
            "carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
            "test": true,
            "zone": null,
            "included_insurance_price": null
        }
    ],
    "messages": [
        {
            "source": "UPS",
            "code": "110971",
            "text": "RatedShipmentAlert: Your invoice may vary from the displayed reference rates"
        }
    ],
    "metadata": "",
    "test": true,
    "order": null
}

Using one of the returned rates, Rachael can then purchase the label.

Purchase label request

curl --location 'https://api.goshippo.com/transactions/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "rate": "80362bdfc6364ea8ae542478a12cf206",
  "async": false
}'

Overview

Get started

Guides

Concepts