> ## Documentation Index > Fetch the complete documentation index at: https://docs.goshippo.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Shippo is a multi-carrier shipping API. For agent integrations that execute shipping operations (rates, labels, tracking, address validation, customs), connect the hosted Shippo MCP server at https://mcp.shippo.com (per-user OAuth; setup at /guides/mcp-server). To search and read this documentation from an agent, a docs search MCP is available at https://docs.goshippo.com/mcp. Shipping workflow knowledge (agent skills and a knowledge pack) is published at https://github.com/goshippo/ai. For REST integrations start at /guides/api-quickstart; test mode uses shippo_test_ API keys. # Get a shipping label > Follow a step-by-step guide to get shipping rates and purchase a label using the Shippo API for your first shipment. **Meet Rachael** Rachael picture Rachael is a small e-commerce business owner, **[www.alltheyarnz.com](http://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](/api-reference/parcels/create-a-new-parcel) that can be referenced over and over again. ```shell Create parcel request theme={null} curl --location 'https://api.goshippo.com/parcels/' \ --header 'Authorization: ShippoToken ' \ --header 'Content-Type: application/json' \ --data '{ "length": 5, "width": 5, "height": 5, "distance_unit": "cm", "weight": 2, "mass_unit": "lb", "template": "", "metadata": "Wool Box1" }' ``` ```json Create parcel response theme={null} { "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](/api-reference/carrier-accounts/list-all-carrier-accounts). ```shell Get carrier account request theme={null} curl --location 'https://api.goshippo.com/carrier_accounts/?carrier=ups' \ --header 'Authorization: ShippoToken ' \ --header 'Content-Type: application/json' ``` ```json Get carrier account response theme={null} { "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](/guides/generate-shipping-label#create-a-shipment-object). The response includes rates available to Rachael from only her preferred carrier. ```shell Create shipment request theme={null} curl --location 'https://api.goshippo.com/shipments/' \ --header 'Authorization: ShippoToken ' \ --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 }' ``` ```json Create shipment response theme={null} "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](/guides/generate-shipping-label#create-a-transaction-object). ```shell Purchase label request theme={null} curl --location 'https://api.goshippo.com/transactions/' \ --header 'Authorization: ShippoToken ' \ --header 'Content-Type: application/json' \ --data '{ "rate": "80362bdfc6364ea8ae542478a12cf206", "async": false }' ``` ## Related topics - [International shipping](/international-shipping/international-shipping.md) - [Retrieve a shipping label](/api-reference/transactions/retrieve-a-shipping-label.md) - [Shipping label sizes](/shipments/shipping-label-sizes.md)