# Shipment The workhorse of the EasyPost API, a `Shipment` is made up of a "to" and "from" `Address`, the `Parcel` being shipped, and any `Forms` required for international deliveries. Once created, a `Shipment` object is used to retrieve shipping `Rates` and purchase a label. A `Shipment` created with a valid `to_address`, `from_address`, and `parcel` will automatically populate its `rates` attribute. --- ## Shipment object | Property | Type | Description | |----------|------|-------------| | id | string | Unique, begins with "shp_" | | object | string | "Shipment" | | mode | string | "test" or "production" | | to_address | Address | The destination address | | from_address | Address | The origin address | | return_address | Address | The shipper's address, defaults to from_address | | buyer_address | Address | The buyer's address, defaults to to_address | | parcel | Parcel | The dimensions and weight of the package | | line_items | array | Used to support carrier claims automation (e.g., USPS carrier claims). Allows storage of item-level product value and description data for each shipment. These values are not passed to the carrier and are not returned in the response. Each item must include: total_line_value (string): Total declared value for the item in USD. item_description (string): Description of the shipped item. | | customs_info | CustomsInfo | Information for the processing of customs | | scan_form | ScanForm | Document created to manifest and scan multiple shipments | | forms | Form array | All associated Form objects | | insurance | string | The associated insurance amount | | rates | Rate array | All associated Rate objects | | selected_rate | Rate | The specific rate purchased for the shipment, or null if unpurchased or purchased through another mechanism | | postage_label | PostageLabel | The associated PostageLabel object | | messages | Message array | Any carrier errors encountered during rating. Discussed in more depth below. | | options | Options | All of the options passed to the shipment, discussed in more depth below | | is_return | boolean | Set true to create as a return. Discussed in more depth below. | | tracking_code | string | If purchased, the tracking code will appear here as well as within the Tracker object. | | usps_zone | integer | The USPS zone of the shipment, if purchased with USPS | | status | string | The current status of the shipment. Possible values: "unknown" "pre_transit" "in_transit" "out_for_delivery" "delivered" "available_for_pickup" "return_to_sender" "failure" "cancelled" "error" | | tracker | Tracker | The associated Tracker object | | fees | Fee array | The associated Fee objects charged to the billing user account | | refund_status | string | The current status of the shipment refund process. Possible values: "submitted" "refunded" "rejected" | | batch_id | string | The ID of the Batch that contains this shipment, if any | | batch_status | string | The current status of the associated BatchShipment | | batch_message | string | The current message of the associated BatchShipment | | created_at | datetime | When the Shipment was created | | updated_at | datetime | When the Shipment was last updated | Example Object: ```json { "id": "shp_a9b97f431c00435cb16ec2d6a14ed109", "created_at": "2025-05-09T20:40:06Z", "is_return": false, "messages": [], "mode": "test", "options": { "currency": "USD", "payment": { "type": "SENDER" }, "date_advance": 0 }, "reference": null, "status": "unknown", "tracking_code": null, "updated_at": "2025-05-09T20:40:06Z", "batch_id": null, "batch_status": null, "batch_message": null, "customs_info": { "id": "cstinfo_35c8cd97c80a47c6807646a34db5f305", "object": "CustomsInfo", "created_at": "2025-05-09T20:40:06Z", "updated_at": "2025-05-09T20:40:06Z", "contents_explanation": "", "contents_type": "merchandise", "customs_certify": true, "customs_signer": "Steve Brule", "eel_pfc": "NOEEI 30.37(a)", "non_delivery_option": "return", "restriction_comments": null, "restriction_type": "none", "mode": "test", "declaration": null, "customs_items": [ { "id": "cstitem_3a28ba5d280f46b48e6d4195fa41a211", "object": "CustomsItem", "created_at": "2025-05-09T20:40:06Z", "updated_at": "2025-05-09T20:40:06Z", "description": "T-shirt", "hs_tariff_number": "123456", "origin_country": "US", "quantity": 1, "value": "10.0", "weight": 5.0, "code": "123", "mode": "test", "manufacturer": null, "currency": null, "eccn": null, "printed_commodity_identifier": null } ] }, "from_address": { "id": "adr_cad8c90a2d1511f0b6ff3cecef1b359e", "object": "Address", "created_at": "2025-05-09T20:40:06+00:00", "updated_at": "2025-05-09T20:40:06+00:00", "name": "EasyPost", "company": null, "street1": "417 Montgomery Street", "street2": "5th Floor", "city": "San Francisco", "state": "CA", "zip": "94104", "country": "US", "phone": "4153334445", "email": "support@easypost.com", "mode": "test", "carrier_facility": null, "residential": null, "federal_tax_id": null, "state_tax_id": null, "verifications": {} }, "insurance": null, "order_id": null, "parcel": { "id": "prcl_aa5a8eb48a92450c93fe5e452303cee2", "object": "Parcel", "created_at": "2025-05-09T20:40:06Z", "updated_at": "2025-05-09T20:40:06Z", "length": 20.2, "width": 10.9, "height": 5.0, "predefined_package": null, "weight": 65.9, "mode": "test" }, "postage_label": null, "rates": [ { "id": "rate_9c291b87bdec47a0b3ed151c60b21fb4", "object": "Rate", "created_at": "2025-05-09T20:40:07Z", "updated_at": "2025-05-09T20:40:07Z", "mode": "test", "service": "Express", "carrier": "USPS", "rate": "51.20", "currency": "USD", "retail_rate": "59.25", "retail_currency": "USD", "list_rate": "51.20", "list_currency": "USD", "billing_type": "easypost", "delivery_days": 2, "delivery_date": null, "delivery_date_guaranteed": false, "est_delivery_days": 2, "shipment_id": "shp_a9b97f431c00435cb16ec2d6a14ed109", "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac" }, { "id": "rate_e5b3aaafb00f48a4ab27d9f20a801b40", "object": "Rate", "created_at": "2025-05-09T20:40:07Z", "updated_at": "2025-05-09T20:40:07Z", "mode": "test", "service": "Priority", "carrier": "USPS", "rate": "11.01", "currency": "USD", "retail_rate": "15.40", "retail_currency": "USD", "list_rate": "11.01", "list_currency": "USD", "billing_type": "easypost", "delivery_days": 2, "delivery_date": null, "delivery_date_guaranteed": false, "est_delivery_days": 2, "shipment_id": "shp_a9b97f431c00435cb16ec2d6a14ed109", "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac" }, { "id": "rate_76e0cae29e294e6db279c76bbe2f27e9", "object": "Rate", "created_at": "2025-05-09T20:40:07Z", "updated_at": "2025-05-09T20:40:07Z", "mode": "test", "service": "GroundAdvantage", "carrier": "USPS", "rate": "8.20", "currency": "USD", "retail_rate": "13.85", "retail_currency": "USD", "list_rate": "9.74", "list_currency": "USD", "billing_type": "easypost", "delivery_days": 3, "delivery_date": null, "delivery_date_guaranteed": false, "est_delivery_days": 3, "shipment_id": "shp_a9b97f431c00435cb16ec2d6a14ed109", "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac" } ], "refund_status": null, "scan_form": null, "selected_rate": null, "tracker": null, "to_address": { "id": "adr_cad6e47c2d1511f094d5ac1f6bc539aa", "object": "Address", "created_at": "2025-05-09T20:40:06+00:00", "updated_at": "2025-05-09T20:40:06+00:00", "name": "Dr. Steve Brule", "company": null, "street1": "179 N Harbor Dr", "street2": null, "city": "Redondo Beach", "state": "CA", "zip": "90277", "country": "US", "phone": "8573875756", "email": "dr_steve_brule@gmail.com", "mode": "test", "carrier_facility": null, "residential": null, "federal_tax_id": null, "state_tax_id": null, "verifications": {} }, "usps_zone": 4, "return_address": { "id": "adr_cad8c90a2d1511f0b6ff3cecef1b359e", "object": "Address", "created_at": "2025-05-09T20:40:06+00:00", "updated_at": "2025-05-09T20:40:06+00:00", "name": "EasyPost", "company": null, "street1": "417 Montgomery Street", "street2": "5th Floor", "city": "San Francisco", "state": "CA", "zip": "94104", "country": "US", "phone": "4153334445", "email": "support@easypost.com", "mode": "test", "carrier_facility": null, "residential": null, "federal_tax_id": null, "state_tax_id": null, "verifications": {} }, "buyer_address": { "id": "adr_cad6e47c2d1511f094d5ac1f6bc539aa", "object": "Address", "created_at": "2025-05-09T20:40:06+00:00", "updated_at": "2025-05-09T20:40:06+00:00", "name": "Dr. Steve Brule", "company": null, "street1": "179 N Harbor Dr", "street2": null, "city": "Redondo Beach", "state": "CA", "zip": "90277", "country": "US", "phone": "8573875756", "email": "dr_steve_brule@gmail.com", "mode": "test", "carrier_facility": null, "residential": null, "federal_tax_id": null, "state_tax_id": null, "verifications": {} }, "forms": [], "fees": [], "object": "Shipment" } ``` --- ## PostageLabel object | Property | Type | Description | |----------|------|-------------| | id | string | Unique, begins with "pl_" | | object | string | "PostageLabel" | | label_date | datetime | The date that appears on the postage label | | label_epl2_url | string | The URL of the EPL2 label file | | label_file_type | string | File type of the label | | label_pdf_url | string | The URL of the PDF label file | | label_resolution | integer | The resolution of the label | | label_size | string | The size of the label | | label_type | string | The type of the label | | label_url | string | The URL of the label file | | label_zpl_url | string | The URL of the ZPL label file | | created_at | datetime | When the PostageLabel was created | | updated_at | datetime | When the PostageLabel was last updated | Example Object: ```json { "id": "shp_55eb159774bc4ecfb06777fce34b7d33", "created_at": "2025-05-09T20:40:10Z", "is_return": false, "messages": [], "mode": "test", "options": { "currency": "USD", "payment": { "type": "SENDER" }, "date_advance": 0 }, "reference": null, "status": "unknown", "tracking_code": "9434600208303109842235", "updated_at": "2025-05-09T20:40:11Z", "batch_id": null, "batch_status": null, "batch_message": null, "customs_info": { "id": "cstinfo_f601ae5718bd469c8531e3749248829a", "object": "CustomsInfo", "created_at": "2025-05-09T20:40:10Z", "updated_at": "2025-05-09T20:40:10Z", "contents_explanation": "", "contents_type": "merchandise", "customs_certify": true, "customs_signer": "Steve Brule", "eel_pfc": "NOEEI 30.37(a)", "non_delivery_option": "return", "restriction_comments": null, "restriction_type": "none", "mode": "test", "declaration": null, "customs_items": [ { "id": "cstitem_6893f3ef878e496ebf90bf27daf879d5", "object": "CustomsItem", "created_at": "2025-05-09T20:40:10Z", "updated_at": "2025-05-09T20:40:10Z", "description": "T-shirt", "hs_tariff_number": "123456", "origin_country": "US", "quantity": 1, "value": "10.0", "weight": 5.0, "code": "123", "mode": "test", "manufacturer": null, "currency": null, "eccn": null, "printed_commodity_identifier": null } ] }, "from_address": { "id": "adr_ccf4bdd42d1511f0967bac1f6bc539aa", "object": "Address", "created_at": "2025-05-09T20:40:10+00:00", "updated_at": "2025-05-09T20:40:10+00:00", "name": "EasyPost", "company": null, "street1": "417 Montgomery Street", "street2": "5th Floor", "city": "San Francisco", "state": "CA", "zip": "94104", "country": "US", "phone": "4153334445", "email": "support@easypost.com", "mode": "test", "carrier_facility": null, "residential": null, "federal_tax_id": null, "state_tax_id": null, "verifications": {} }, "insurance": null, "order_id": null, "parcel": { "id": "prcl_398ef47ef288457a8967d18b400d877e", "object": "Parcel", "created_at": "2025-05-09T20:40:10Z", "updated_at": "2025-05-09T20:40:10Z", "length": 20.2, "width": 10.9, "height": 5.0, "predefined_package": null, "weight": 65.9, "mode": "test" }, "postage_label": { "object": "PostageLabel", "id": "pl_6270007cad7643eaad274bb5c71e9614", "created_at": "2025-05-09T20:40:11Z", "updated_at": "2025-05-09T20:40:12Z", "date_advance": 0, "integrated_form": "none", "label_date": "2025-05-09T20:40:11Z", "label_resolution": 300, "label_size": "4x6", "label_type": "default", "label_file_type": "image/png", "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20250509/e857a7afd19edf498587cd09e2564722ab.png", "label_pdf_url": null, "label_zpl_url": "https://easypost-files.s3-us-west-2.amazonaws.com/files/postage_label/20250509/cbed7645eafc4a23af370b4525144fc3.zpl", "label_epl2_url": null, "label_file": null }, "rates": [ { "id": "rate_8f21e20a210249f7b7dec4f8a0f5a09f", "object": "Rate", "created_at": "2025-05-09T20:40:10Z", "updated_at": "2025-05-09T20:40:10Z", "mode": "test", "service": "Express", "carrier": "USPS", "rate": "51.20", "currency": "USD", "retail_rate": "59.25", "retail_currency": "USD", "list_rate": "51.20", "list_currency": "USD", "billing_type": "easypost", "delivery_days": 2, "delivery_date": null, "delivery_date_guaranteed": false, "est_delivery_days": 2, "shipment_id": "shp_55eb159774bc4ecfb06777fce34b7d33", "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac" }, { "id": "rate_50c5205056e14b95b3e921aff00a9e91", "object": "Rate", "created_at": "2025-05-09T20:40:10Z", "updated_at": "2025-05-09T20:40:10Z", "mode": "test", "service": "Priority", "carrier": "USPS", "rate": "11.01", "currency": "USD", "retail_rate": "15.40", "retail_currency": "USD", "list_rate": "11.01", "list_currency": "USD", "billing_type": "easypost", "delivery_days": 2, "delivery_date": null, "delivery_date_guaranteed": false, "est_delivery_days": 2, "shipment_id": "shp_55eb159774bc4ecfb06777fce34b7d33", "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac" }, { "id": "rate_8ba81ced929549fdaf5ddfc21c852c8f", "object": "Rate", "created_at": "2025-05-09T20:40:10Z", "updated_at": "2025-05-09T20:40:10Z", "mode": "test", "service": "GroundAdvantage", "carrier": "USPS", "rate": "8.20", "currency": "USD", "retail_rate": "13.85", "retail_currency": "USD", "list_rate": "9.74", "list_currency": "USD", "billing_type": "easypost", "delivery_days": 3, "delivery_date": null, "delivery_date_guaranteed": false, "est_delivery_days": 3, "shipment_id": "shp_55eb159774bc4ecfb06777fce34b7d33", "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac" } ], "refund_status": null, "scan_form": null, "selected_rate": { "id": "rate_8ba81ced929549fdaf5ddfc21c852c8f", "object": "Rate", "created_at": "2025-05-09T20:40:11Z", "updated_at": "2025-05-09T20:40:11Z", "mode": "test", "service": "GroundAdvantage", "carrier": "USPS", "rate": "8.20", "currency": "USD", "retail_rate": "13.85", "retail_currency": "USD", "list_rate": "9.74", "list_currency": "USD", "billing_type": "easypost", "delivery_days": 3, "delivery_date": null, "delivery_date_guaranteed": false, "est_delivery_days": 3, "shipment_id": "shp_55eb159774bc4ecfb06777fce34b7d33", "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac" }, "tracker": { "id": "trk_00760f5158574ef4a062a09c5848dcff", "object": "Tracker", "mode": "test", "tracking_code": "9434600208303109842235", "status": "pre_transit", "status_detail": "status_update", "created_at": "2025-05-09T20:40:11Z", "updated_at": "2025-05-09T20:40:11Z", "signed_by": null, "weight": null, "est_delivery_date": "2025-05-09T20:40:11Z", "shipment_id": "shp_55eb159774bc4ecfb06777fce34b7d33", "carrier": "USPS", "tracking_details": [ { "object": "TrackingDetail", "message": "Pre-Shipment Info Sent to USPS", "description": "", "status": "pre_transit", "status_detail": "status_update", "datetime": "2025-04-09T20:40:11Z", "source": "USPS", "carrier_code": "", "tracking_location": { "object": "TrackingLocation", "city": null, "state": null, "country": null, "zip": null }, "est_delivery_date": null }, { "object": "TrackingDetail", "message": "Shipping Label Created", "description": "", "status": "pre_transit", "status_detail": "status_update", "datetime": "2025-04-10T09:17:11Z", "source": "USPS", "carrier_code": "", "tracking_location": { "object": "TrackingLocation", "city": "HOUSTON", "state": "TX", "country": null, "zip": "77063" }, "est_delivery_date": null } ], "fees": [], "carrier_detail": { "object": "CarrierDetail", "service": "First-Class Package Service", "container_type": null, "est_delivery_date_local": null, "est_delivery_time_local": null, "origin_location": "HOUSTON TX, 77001", "origin_tracking_location": { "object": "TrackingLocation", "city": "HOUSTON", "state": "TX", "country": null, "zip": "77063" }, "destination_location": "CHARLESTON SC, 29401", "destination_tracking_location": null, "guaranteed_delivery_date": null, "alternate_identifier": null, "initial_delivery_attempt": null }, "public_url": "https://track.easypost.com/djE6dHJrXzAwNzYwZjUxNTg1NzRlZjRhMDYyYTA5YzU4NDhkY2Zm" }, "to_address": { "id": "adr_ccf1e01f2d1511f09676ac1f6bc539aa", "object": "Address", "created_at": "2025-05-09T20:40:10+00:00", "updated_at": "2025-05-09T20:40:10+00:00", "name": "DR. STEVE BRULE", "company": null, "street1": "179 N HARBOR DR", "street2": null, "city": "REDONDO BEACH", "state": "CA", "zip": "90277-2506", "country": "US", "phone": "8573875756", "email": "DR_STEVE_BRULE@GMAIL.COM", "mode": "test", "carrier_facility": null, "residential": false, "federal_tax_id": null, "state_tax_id": null, "verifications": { "zip4": { "success": true, "errors": [], "details": null }, "delivery": { "success": true, "errors": [], "details": { "latitude": 33.8436, "longitude": -118.39177, "time_zone": "America/Los_Angeles" } } } }, "usps_zone": 4, "return_address": { "id": "adr_ccf4bdd42d1511f0967bac1f6bc539aa", "object": "Address", "created_at": "2025-05-09T20:40:10+00:00", "updated_at": "2025-05-09T20:40:10+00:00", "name": "EasyPost", "company": null, "street1": "417 Montgomery Street", "street2": "5th Floor", "city": "San Francisco", "state": "CA", "zip": "94104", "country": "US", "phone": "4153334445", "email": "support@easypost.com", "mode": "test", "carrier_facility": null, "residential": null, "federal_tax_id": null, "state_tax_id": null, "verifications": {} }, "buyer_address": { "id": "adr_ccf1e01f2d1511f09676ac1f6bc539aa", "object": "Address", "created_at": "2025-05-09T20:40:10+00:00", "updated_at": "2025-05-09T20:40:10+00:00", "name": "DR. STEVE BRULE", "company": null, "street1": "179 N HARBOR DR", "street2": null, "city": "REDONDO BEACH", "state": "CA", "zip": "90277-2506", "country": "US", "phone": "8573875756", "email": "DR_STEVE_BRULE@GMAIL.COM", "mode": "test", "carrier_facility": null, "residential": false, "federal_tax_id": null, "state_tax_id": null, "verifications": { "zip4": { "success": true, "errors": [], "details": null }, "delivery": { "success": true, "errors": [], "details": { "latitude": 33.8436, "longitude": -118.39177, "time_zone": "America/Los_Angeles" } } } }, "forms": [], "fees": [ { "object": "Fee", "type": "PostageFee", "amount": "8.20000", "charged": true, "refunded": false } ], "object": "Shipment" } ``` --- ## Create a Shipment ### Example: POST /shipments #### cURL ```shell curl -X POST https://api.easypost.com/v2/shipments \ -u "EASYPOST_API_KEY": \ -H 'Content-Type: application/json' \ -d '{ "shipment": { "to_address": { "name": "Dr. Steve Brule", "street1": "179 N Harbor Dr", "city": "Redondo Beach", "state": "CA", "zip": "90277", "country": "US", "phone": "8573875756", "email": "dr_steve_brule@gmail.com" }, "from_address": { "name": "EasyPost", "street1": "417 Montgomery Street", "street2": "5th Floor", "city": "San Francisco", "state": "CA", "zip": "94104", "country": "US", "phone": "4153334445", "email": "support@easypost.com" }, "parcel": { "length": "20.2", "width": "10.9", "height": "5", "weight": "65.9" }, "customs_info": { "id": "cstinfo_..." } } }' ``` #### Go ```go package example import ( "fmt" "github.com/EasyPost/easypost-go/v5" ) func create() { client := easypost.New("EASYPOST_API_KEY") shipment, _ := client.CreateShipment( &easypost.Shipment{ ToAddress: &easypost.Address{ Name: "Dr. Steve Brule", Street1: "179 N Harbor Dr", City: "Redondo Beach", State: "CA", Zip: "90277", Country: "US", Phone: "4155559999", Email: "dr_steve_brule@gmail.com", }, FromAddress: &easypost.Address{ Name: "EasyPost", Street1: "417 Montgomery Street", Street2: "5th Floor", City: "San Francisco", State: "CA", Zip: "90277", Country: "US", Phone: "4155559999", Email: "support@easypost.com", }, Parcel: &easypost.Parcel{ Length: 20.2, Width: 10.9, Height: 5, Weight: 65.9, }, CustomsInfo: &easypost.CustomsInfo{ ID: "cstinfo_...", }, }, ) fmt.Println(shipment) } ``` #### Java ```java package shipments; import com.easypost.exception.EasyPostException; import com.easypost.model.Shipment; import com.easypost.service.EasyPostClient; import java.util.HashMap; public class Create { public static void main(String[] args) throws EasyPostException { EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY"); HashMap toAddressMap = new HashMap(); toAddressMap.put("name", "Dr. Steve Brule"); toAddressMap.put("street1", "179 N Harbor Dr"); toAddressMap.put("city", "Redondo Beach"); toAddressMap.put("state", "CA"); toAddressMap.put("country", "US"); toAddressMap.put("phone", "8573875756"); toAddressMap.put("email", "dr_steve_brule@gmail.com"); toAddressMap.put("zip", "90277"); HashMap fromAddressMap = new HashMap(); fromAddressMap.put("name", "EasyPost"); fromAddressMap.put("street1", "417 Montgomery Street"); fromAddressMap.put("street2", "5th Floor"); fromAddressMap.put("city", "San Francisco"); fromAddressMap.put("state", "CA"); fromAddressMap.put("zip", "94104"); fromAddressMap.put("country", "US"); fromAddressMap.put("phone", "4153334445"); fromAddressMap.put("email", "support@easypost.com"); HashMap parcelMap = new HashMap(); parcelMap.put("length", 20.2); parcelMap.put("width", 10.9); parcelMap.put("height", 5); parcelMap.put("weight", 65.9); HashMap customsInfoMap = new HashMap(); customsInfoMap.put("id", "cstinfo_..."); HashMap params = new HashMap(); params.put("to_address", toAddressMap); params.put("from_address", fromAddressMap); params.put("parcel", parcelMap); params.put("customs_info", customsInfoMap); Shipment shipment = client.shipment.create(params); System.out.println(shipment); } } ``` #### C# ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using EasyPost; using Newtonsoft.Json; namespace EasyPostExamples { public class Examples { public static async Task Main() { var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY")); // Create a shipment using all data in one API call EasyPost.Parameters.Shipment.Create parameters = new() { ToAddress = new EasyPost.Parameters.Address.Create { Name = "Dr. Steve Brule", Street1 = "417 Montgomery Street", Street2 = "5th Floor", City = "San Francisco", State = "CA", Country = "US", Zip = "94104" }, FromAddress = new EasyPost.Parameters.Address.Create { Company = "EasyPost", Street1 = "417 Montgomery Street", Street2 = "Floor 5", City = "San Francisco", State = "CA", Country = "US", Zip = "94104" }, Parcel = new EasyPost.Parameters.Parcel.Create { Length = 8, Width = 6, Height = 5, Weight = 10 }, CustomsInfo = new EasyPost.Parameters.CustomsInfo.Create { // ... } }; EasyPost.Models.API.Shipment shipment = await client.Shipment.Create(parameters); Console.WriteLine(JsonConvert.SerializeObject(shipment, Formatting.Indented)); // Create a shipment using existing addresses, parcel, and customs info EasyPost.Models.API.Address toAddress = await client.Address.Retrieve("adr_..."); EasyPost.Models.API.Address fromAddress = await client.Address.Retrieve("adr_..."); EasyPost.Models.API.Parcel parcel = await client.Parcel.Retrieve("prcl_..."); EasyPost.Models.API.CustomsInfo customsInfo = await client.CustomsInfo.Retrieve("cstinfo_..."); parameters = new() { ToAddress = toAddress, FromAddress = fromAddress, Parcel = parcel, CustomsInfo = customsInfo }; shipment = await client.Shipment.Create(parameters); Console.WriteLine(JsonConvert.SerializeObject(shipmentWithIds, Formatting.Indented)); } } } ``` #### Node.js ```javascript const EasyPostClient = require('@easypost/api'); const client = new EasyPostClient('EASYPOST_API_KEY'); (async () => { let shipment; shipment = await client.Shipment.create({ to_address: { name: 'Dr. Steve Brule', street1: '179 N Harbor Dr', city: 'Redondo Beach', state: 'CA', zip: '90277', country: 'US', email: 'dr_steve_brule@gmail.com', phone: '4155559999', }, from_address: { street1: '417 montgomery street', street2: 'FL 5', city: 'San Francisco', state: 'CA', zip: '94104', country: 'US', company: 'EasyPost', phone: '415-123-4567', }, parcel: { length: 20.2, width: 10.9, height: 5, weight: 65.9, }, customs_info: { id: 'cstinfo_...' }, }); // or create by using IDs shipment = await client.Shipment.create({ to_address: { id: 'adr_...' }, from_address: { id: 'adr_...' }, parcel: { id: 'prcl_...' }, customs_info: { id: 'cstinfo_...' }, }); console.log(shipment); })(); ``` #### PHP ```php shipment->create([ 'to_address' => [ 'name' => 'Dr. Steve Brule', 'street1' => '179 N Harbor Dr', 'city' => 'Redondo Beach', 'state' => 'CA', 'zip' => '90277', 'country' => 'US', 'phone' => '3331114444', 'email' => 'dr_steve_brule@gmail.com' ], 'from_address' => [ 'name' => 'EasyPost', 'street1' => '417 Montgomery Street', 'street2' => '5th Floor', 'city' => 'San Francisco', 'state' => 'CA', 'zip' => '94104', 'country' => 'US', 'phone' => '3331114444', 'email' => 'support@easypost.com' ], 'parcel' => [ 'length' => 20.2, 'width' => 10.9, 'height' => 5, 'weight' => 65.9 ] ]); echo $shipment; ``` #### Python ```python import easypost client = easypost.EasyPostClient("EASYPOST_API_KEY") shipment = client.shipment.create( to_address={ "name": "Dr. Steve Brule", "street1": "179 N Harbor Dr", "city": "Redondo Beach", "state": "CA", "zip": "90277", "country": "US", "phone": "4153334444", "email": "dr_steve_brule@gmail.com", }, from_address={ "name": "EasyPost", "street1": "417 Montgomery Street", "street2": "5th Floor", "city": "San Francisco", "state": "CA", "zip": "94104", "country": "US", "phone": "4153334444", "email": "support@easypost.com", }, parcel={ "length": 20.2, "width": 10.9, "height": 5, "weight": 65.9, }, customs_info={"id": "cstinfo_..."}, ) # or create by using IDs shipment = client.shipment.create( to_address={"id": "adr_..."}, from_address={"id": "adr_..."}, parcel={"id": "prcl_..."}, customs_info={"id": "cstinfo_..."}, ) print(shipment) ``` #### Ruby ```ruby require 'easypost' client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY') shipment = client.shipment.create( to_address: { name: 'Dr. Steve Brule', street1: '179 N Harbor Dr', city: 'Redondo Beach', state: 'CA', zip: '90277', country: 'US', phone: '4155559999', email: 'dr_steve_brule@gmail.com', }, from_address: { name: 'EasyPost', street1: '417 Montgomery Street', street2: '5th Floor', city: 'San Francisco', state: 'CA', zip: '94104', country: 'US', phone: '4153334445', email: 'support@easypost.com', }, parcel: { length: 20.2, width: 10.9, height: 5, weight: 65.9, }, customs_info: { id: 'cstinfo_...', }, ) puts shipment ``` A `Shipment` is almost exclusively a container for other objects, and thus a `Shipment` may reuse many of these objects. Additionally, all the objects contained within a `Shipment` may be created at the same time. The origin/destination `Address` and `Parcel` are required for rating. `CustomInfo` is required to rate an international `Shipment`, this includes when the destination is a U.S. territory. The associated `Tracker`,`Fee`, and `Rates` are generated by EasyPost and cannot be modified by the user. You can limit the `CarrierAccounts` to use for rating by passing the `carrier_accounts` parameter. If the `CarrierAccount` IDs provided are invalid or disabled, the shipment creation call will result in an error. [Note: This object is immutable after creation. Review the rendered documentation for details.] {/* END: Create a Shipment */} --- ## Buy a Shipment ### Example: POST /shipments/:id/buy #### cURL ```shell curl -X POST https://api.easypost.com/v2/shipments \ -u "EASYPOST_API_KEY": \ -H 'Content-Type: application/json' \ -d '{ "shipment": { "to_address": { "name": "Dr. Steve Brule", "street1": "179 N Harbor Dr", "city": "Redondo Beach", "state": "CA", "zip": "90277", "country": "US", "phone": "8573875756", "email": "dr_steve_brule@gmail.com" }, "from_address": { "name": "EasyPost", "street1": "417 Montgomery Street", "street2": "5th Floor", "city": "San Francisco", "state": "CA", "zip": "94104", "country": "US", "phone": "4153334445", "email": "support@easypost.com" }, "parcel": { "length": "20.2", "width": "10.9", "height": "5", "weight": "65.9" }, "customs_info": { "id": "cstinfo_..." } } }' ``` #### Go ```go package example import ( "fmt" "github.com/EasyPost/easypost-go/v5" ) func create() { client := easypost.New("EASYPOST_API_KEY") shipment, _ := client.CreateShipment( &easypost.Shipment{ ToAddress: &easypost.Address{ Name: "Dr. Steve Brule", Street1: "179 N Harbor Dr", City: "Redondo Beach", State: "CA", Zip: "90277", Country: "US", Phone: "4155559999", Email: "dr_steve_brule@gmail.com", }, FromAddress: &easypost.Address{ Name: "EasyPost", Street1: "417 Montgomery Street", Street2: "5th Floor", City: "San Francisco", State: "CA", Zip: "90277", Country: "US", Phone: "4155559999", Email: "support@easypost.com", }, Parcel: &easypost.Parcel{ Length: 20.2, Width: 10.9, Height: 5, Weight: 65.9, }, CustomsInfo: &easypost.CustomsInfo{ ID: "cstinfo_...", }, }, ) fmt.Println(shipment) } ``` #### Java ```java package shipments; import com.easypost.exception.EasyPostException; import com.easypost.model.Shipment; import com.easypost.service.EasyPostClient; import java.util.HashMap; public class Create { public static void main(String[] args) throws EasyPostException { EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY"); HashMap toAddressMap = new HashMap(); toAddressMap.put("name", "Dr. Steve Brule"); toAddressMap.put("street1", "179 N Harbor Dr"); toAddressMap.put("city", "Redondo Beach"); toAddressMap.put("state", "CA"); toAddressMap.put("country", "US"); toAddressMap.put("phone", "8573875756"); toAddressMap.put("email", "dr_steve_brule@gmail.com"); toAddressMap.put("zip", "90277"); HashMap fromAddressMap = new HashMap(); fromAddressMap.put("name", "EasyPost"); fromAddressMap.put("street1", "417 Montgomery Street"); fromAddressMap.put("street2", "5th Floor"); fromAddressMap.put("city", "San Francisco"); fromAddressMap.put("state", "CA"); fromAddressMap.put("zip", "94104"); fromAddressMap.put("country", "US"); fromAddressMap.put("phone", "4153334445"); fromAddressMap.put("email", "support@easypost.com"); HashMap parcelMap = new HashMap(); parcelMap.put("length", 20.2); parcelMap.put("width", 10.9); parcelMap.put("height", 5); parcelMap.put("weight", 65.9); HashMap customsInfoMap = new HashMap(); customsInfoMap.put("id", "cstinfo_..."); HashMap params = new HashMap(); params.put("to_address", toAddressMap); params.put("from_address", fromAddressMap); params.put("parcel", parcelMap); params.put("customs_info", customsInfoMap); Shipment shipment = client.shipment.create(params); System.out.println(shipment); } } ``` #### C# ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using EasyPost; using Newtonsoft.Json; namespace EasyPostExamples { public class Examples { public static async Task Main() { var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY")); // Create a shipment using all data in one API call EasyPost.Parameters.Shipment.Create parameters = new() { ToAddress = new EasyPost.Parameters.Address.Create { Name = "Dr. Steve Brule", Street1 = "417 Montgomery Street", Street2 = "5th Floor", City = "San Francisco", State = "CA", Country = "US", Zip = "94104" }, FromAddress = new EasyPost.Parameters.Address.Create { Company = "EasyPost", Street1 = "417 Montgomery Street", Street2 = "Floor 5", City = "San Francisco", State = "CA", Country = "US", Zip = "94104" }, Parcel = new EasyPost.Parameters.Parcel.Create { Length = 8, Width = 6, Height = 5, Weight = 10 }, CustomsInfo = new EasyPost.Parameters.CustomsInfo.Create { // ... } }; EasyPost.Models.API.Shipment shipment = await client.Shipment.Create(parameters); Console.WriteLine(JsonConvert.SerializeObject(shipment, Formatting.Indented)); // Create a shipment using existing addresses, parcel, and customs info EasyPost.Models.API.Address toAddress = await client.Address.Retrieve("adr_..."); EasyPost.Models.API.Address fromAddress = await client.Address.Retrieve("adr_..."); EasyPost.Models.API.Parcel parcel = await client.Parcel.Retrieve("prcl_..."); EasyPost.Models.API.CustomsInfo customsInfo = await client.CustomsInfo.Retrieve("cstinfo_..."); parameters = new() { ToAddress = toAddress, FromAddress = fromAddress, Parcel = parcel, CustomsInfo = customsInfo }; shipment = await client.Shipment.Create(parameters); Console.WriteLine(JsonConvert.SerializeObject(shipmentWithIds, Formatting.Indented)); } } } ``` #### Node.js ```javascript const EasyPostClient = require('@easypost/api'); const client = new EasyPostClient('EASYPOST_API_KEY'); (async () => { let shipment; shipment = await client.Shipment.create({ to_address: { name: 'Dr. Steve Brule', street1: '179 N Harbor Dr', city: 'Redondo Beach', state: 'CA', zip: '90277', country: 'US', email: 'dr_steve_brule@gmail.com', phone: '4155559999', }, from_address: { street1: '417 montgomery street', street2: 'FL 5', city: 'San Francisco', state: 'CA', zip: '94104', country: 'US', company: 'EasyPost', phone: '415-123-4567', }, parcel: { length: 20.2, width: 10.9, height: 5, weight: 65.9, }, customs_info: { id: 'cstinfo_...' }, }); // or create by using IDs shipment = await client.Shipment.create({ to_address: { id: 'adr_...' }, from_address: { id: 'adr_...' }, parcel: { id: 'prcl_...' }, customs_info: { id: 'cstinfo_...' }, }); console.log(shipment); })(); ``` #### PHP ```php shipment->create([ 'to_address' => [ 'name' => 'Dr. Steve Brule', 'street1' => '179 N Harbor Dr', 'city' => 'Redondo Beach', 'state' => 'CA', 'zip' => '90277', 'country' => 'US', 'phone' => '3331114444', 'email' => 'dr_steve_brule@gmail.com' ], 'from_address' => [ 'name' => 'EasyPost', 'street1' => '417 Montgomery Street', 'street2' => '5th Floor', 'city' => 'San Francisco', 'state' => 'CA', 'zip' => '94104', 'country' => 'US', 'phone' => '3331114444', 'email' => 'support@easypost.com' ], 'parcel' => [ 'length' => 20.2, 'width' => 10.9, 'height' => 5, 'weight' => 65.9 ] ]); echo $shipment; ``` #### Python ```python import easypost client = easypost.EasyPostClient("EASYPOST_API_KEY") shipment = client.shipment.create( to_address={ "name": "Dr. Steve Brule", "street1": "179 N Harbor Dr", "city": "Redondo Beach", "state": "CA", "zip": "90277", "country": "US", "phone": "4153334444", "email": "dr_steve_brule@gmail.com", }, from_address={ "name": "EasyPost", "street1": "417 Montgomery Street", "street2": "5th Floor", "city": "San Francisco", "state": "CA", "zip": "94104", "country": "US", "phone": "4153334444", "email": "support@easypost.com", }, parcel={ "length": 20.2, "width": 10.9, "height": 5, "weight": 65.9, }, customs_info={"id": "cstinfo_..."}, ) # or create by using IDs shipment = client.shipment.create( to_address={"id": "adr_..."}, from_address={"id": "adr_..."}, parcel={"id": "prcl_..."}, customs_info={"id": "cstinfo_..."}, ) print(shipment) ``` #### Ruby ```ruby require 'easypost' client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY') shipment = client.shipment.create( to_address: { name: 'Dr. Steve Brule', street1: '179 N Harbor Dr', city: 'Redondo Beach', state: 'CA', zip: '90277', country: 'US', phone: '4155559999', email: 'dr_steve_brule@gmail.com', }, from_address: { name: 'EasyPost', street1: '417 Montgomery Street', street2: '5th Floor', city: 'San Francisco', state: 'CA', zip: '94104', country: 'US', phone: '4153334445', email: 'support@easypost.com', }, parcel: { length: 20.2, width: 10.9, height: 5, weight: 65.9, }, customs_info: { id: 'cstinfo_...', }, ) puts shipment ``` To purchase a `Shipment`, specify the `Rate` to buy. This operation returns the `tracking_code` and `postage_label` attributes. The default image format for the `PostageLabel` is PNG. To use a different format, refer to the `label_format` option in the Options object. For certain hybrid carrier services, including DHL eCommerce, FedEx Ground Economy, UPS Ground Saver, and Veho, EasyPost may receive multiple carrier tracking numbers for a single shipment. When available from the carrier at label creation time, a secondary (alternate) tracking number is returned in `tracker.carrier_detail.alternate_identifier`. If it is not immediately available, it may still populate asynchronously on the Tracker resource after label purchase. Availability and timing vary by carrier. Insurance may be added at the time of purchase by including the `insurance` attribute as a string. All insurance values must be in U.S. dollars (USD). {/* END: Buy a Shipment */} --- ## Buy a Shipment without rating (One-Call Buy) ### Example: One-Call Buy #### cURL ```shell curl -X POST https://api.easypost.com/v2/shipments \ -u "EASYPOST_API_KEY": \ -H 'Content-Type: application/json' \ -d '{ "shipment": { "to_address": { "name": "Dr. Steve Brule", "street1": "179 N Harbor Dr", "city": "Redondo Beach", "state": "CA", "zip": "90277", "country": "US", "phone": "8573875756", "email": "dr_steve_brule@gmail.com" }, "from_address": { "name": "EasyPost", "street1": "417 Montgomery Street", "street2": "5th Floor", "city": "San Francisco", "state": "CA", "zip": "94104", "country": "US", "phone": "4153334445", "email": "support@easypost.com" }, "parcel": { "length": "20.2", "width": "10.9", "height": "5", "weight": "65.9" }, "service": "NextDayAir", "carrier_accounts": ["ca_..."] } }' ``` #### Go ```go package example import ( "fmt" "github.com/EasyPost/easypost-go/v5" ) func oneCallBuy() { client := easypost.New("EASYPOST_API_KEY") shipment, _ := client.CreateShipment( &easypost.Shipment{ CarrierAccountIDs: []string{"ca_..."}, Service: "NextDayAir", Parcel: &easypost.Parcel{ Length: 20.2, Width: 10.9, Height: 5, Weight: 65.9, }, ToAddress: &easypost.Address{ Name: "Dr. Steve Brule", Street1: "179 N Harbor Dr", City: "Redondo Beach", State: "CA", Zip: "90277", Country: "US", Phone: "4155559999", Email: "dr_steve_brule@gmail.com", }, FromAddress: &easypost.Address{ Name: "EasyPost", Street1: "417 Montgomery Street", Street2: "5th Floor", City: "San Francisco", State: "CA", Zip: "90277", Country: "US", Phone: "4155559999", Email: "support@easypost.com", }, Reference: "ShipmentRef", }, ) fmt.Println(shipment) } ``` #### Java ```java package shipments; import com.easypost.exception.EasyPostException; import com.easypost.model.Shipment; import com.easypost.service.EasyPostClient; import java.util.HashMap; public class OneCallBuy { public static void main(String[] args) throws EasyPostException { EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY"); HashMap toAddressMap = new HashMap(); toAddressMap.put("name", "Dr. Steve Brule"); toAddressMap.put("street1", "179 N Harbor Dr"); toAddressMap.put("city", "Redondo Beach"); toAddressMap.put("state", "CA"); toAddressMap.put("country", "US"); toAddressMap.put("phone", "8573875756"); toAddressMap.put("email", "dr_steve_brule@gmail.com"); toAddressMap.put("zip", "90277"); HashMap fromAddressMap = new HashMap(); fromAddressMap.put("name", "EasyPost"); fromAddressMap.put("street1", "417 Montgomery Street"); fromAddressMap.put("street2", "5th Floor"); fromAddressMap.put("city", "San Francisco"); fromAddressMap.put("state", "CA"); fromAddressMap.put("zip", "94104"); fromAddressMap.put("country", "US"); fromAddressMap.put("phone", "4153334445"); fromAddressMap.put("email", "support@easypost.com"); HashMap parcelMap = new HashMap(); parcelMap.put("length", 20.2); parcelMap.put("width", 10.9); parcelMap.put("height", 5); parcelMap.put("weight", 65.9); HashMap customsInfoMap = new HashMap(); customsInfoMap.put("id", "cstinfo_..."); HashMap params = new HashMap(); params.put("to_address", toAddressMap); params.put("from_address", fromAddressMap); params.put("parcel", parcelMap); params.put("customs_info", customsInfoMap); params.put("carrier_accounts", "ca_..."); params.put("service", "NextDayAir"); Shipment shipment = client.shipment.create(params); System.out.println(shipment); } } ``` #### C# ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using EasyPost; using Newtonsoft.Json; namespace EasyPostExamples { public class Examples { public static async Task Main() { var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY")); EasyPost.Parameters.Shipment.Create parameters = new() { ToAddress = new EasyPost.Parameters.Address.Create { Name = "Dr. Steve Brule", Street1 = "417 Montgomery Street", Street2 = "5th Floor", City = "San Francisco", State = "CA", Country = "US", Zip = "94104" }, FromAddress = new EasyPost.Parameters.Address.Create { Company = "EasyPost", Street1 = "417 Montgomery Street", Street2 = "Floor 5", City = "San Francisco", State = "CA", Country = "US", Zip = "94104" }, Parcel = new EasyPost.Parameters.Parcel.Create { Length = 8, Width = 6, Height = 5, Weight = 10 }, Service = "NextDayAir", CarrierAccountIds = new List { "ca_..." } }; EasyPost.Models.API.Shipment shipment = await client.Shipment.Create(parameters); Console.WriteLine(JsonConvert.SerializeObject(shipment, Formatting.Indented)); } } } ``` #### Node.js ```javascript const EasyPostClient = require('@easypost/api'); const client = new EasyPostClient('EASYPOST_API_KEY'); (async () => { const shipment = await client.Shipment.create({ carrier_accounts: ['ca_...'], service: 'NextDayAir', to_address: { name: 'Dr. Steve Brule', street1: '179 N Harbor Dr', city: 'Redondo Beach', state: 'CA', zip: '90277', country: 'US', email: 'dr_steve_brule@gmail.com', phone: '4155559999', }, from_address: { street1: '417 montgomery street', street2: 'FL 5', city: 'San Francisco', state: 'CA', zip: '94104', country: 'US', company: 'EasyPost', phone: '415-123-4567', }, parcel: { length: 20.2, width: 10.9, height: 5, weight: 65.9, }, }); console.log(shipment); })(); ``` #### PHP ```php shipment->create([ 'carrier_accounts' => ['ca_...'], 'service' => 'NextDayAir', 'to_address' => [ 'name' => 'Dr. Steve Brule', 'street1' => '179 N Harbor Dr', 'city' => 'Redondo Beach', 'state' => 'CA', 'zip' => '90277', 'country' => 'US', 'phone' => '3331114444', 'email' => 'dr_steve_brule@gmail.com' ], 'from_address' => [ 'name' => 'EasyPost', 'street1' => '417 Montgomery Street', 'street2' => '5th Floor', 'city' => 'San Francisco', 'state' => 'CA', 'zip' => '94104', 'country' => 'US', 'phone' => '3331114444', 'email' => 'support@easypost.com' ], 'parcel' => [ 'length' => 20.2, 'width' => 10.9, 'height' => 5, 'weight' => 65.9 ] ]); echo $shipment; ``` #### Python ```python import easypost client = easypost.EasyPostClient("EASYPOST_API_KEY") shipment = client.shipment.create( carrier_accounts=["ca_..."], service="NextDayAir", to_address={ "name": "Dr. Steve Brule", "street1": "179 N Harbor Dr", "city": "Redondo Beach", "state": "CA", "zip": "90277", "country": "US", "phone": "4153334444", "email": "dr_steve_brule@gmail.com", }, from_address={ "name": "EasyPost", "street1": "417 Montgomery Street", "street2": "5th Floor", "city": "San Francisco", "state": "CA", "zip": "94104", "country": "US", "phone": "4153334444", "email": "support@easypost.com", }, parcel={ "length": 20.2, "width": 10.9, "height": 5, "weight": 65.9, }, ) print(shipment) ``` #### Ruby ```ruby require 'easypost' client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY') shipment = client.shipment.create( to_address: { name: 'Dr. Steve Brule', street1: '179 N Harbor Dr', city: 'Redondo Beach', state: 'CA', zip: '90277', country: 'US', phone: '8573875756', email: 'dr_steve_brule@gmail.com', }, from_address: { name: 'EasyPost', street1: '417 Montgomery Street', street2: '5th Floor', city: 'San Francisco', state: 'CA', zip: '94104', country: 'US', phone: '4153334445', email: 'support@easypost.com', }, parcel: { length: 20.2, width: 10.9, height: 5, weight: 65.9, }, service: 'NextDayAir', carrier_accounts: ['ca_...'], ) puts shipment ``` The one-call buy method enables shipment creation and label purchase in a single API call. This approach is suitable when the desired service level is already known, or a flat-rate agreement is in place with the carrier. For certain hybrid carrier services, including DHL eCommerce, FedEx Ground Economy, UPS Ground Saver, and Veho, the response may include `tracker.carrier_detail.alternate_identifier` when an alternate tracking identifier is available from the carrier at label creation time. If it is not immediately available, it may still populate asynchronously on the Tracker resource after label purchase. Availability and timing vary by carrier. Using this method can reduce API calls and improve integration performance by skipping the standard two-step process ( "Create `Shipment`" followed by "Buy `Shipment`"). To utilize one-call buy, specify the `CarrierAccount` and service level name directly in the Create `Shipment` call. Insurance may be added at the time of purchase by including the `insurance` attribute within the `shipment` object as a string. All insurance values must be in U.S. dollars (USD). {/* END: Buy a Shipment without rating */} --- ## Retrieve all Shipments ### Example: GET /shipments #### cURL ```shell curl -X GET "https://api.easypost.com/v2/shipments?page_size=5" \ -u "EASYPOST_API_KEY": ``` #### Go ```go package example import ( "fmt" "github.com/EasyPost/easypost-go/v5" ) func list() { client := easypost.New("EASYPOST_API_KEY") shipments, _ := client.ListShipments( &easypost.ListShipmentsOptions{ PageSize: 5, }, ) fmt.Println(shipments) } ``` #### Java ```java package shipments; import com.easypost.exception.EasyPostException; import com.easypost.model.ShipmentCollection; import com.easypost.service.EasyPostClient; import java.util.HashMap; public class All { public static void main(String[] args) throws EasyPostException { EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY"); HashMap params = new HashMap<>(); params.put("page_size", 5); ShipmentCollection shipments = client.shipment.all(params); System.out.println(shipments); } } ``` #### C# ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using EasyPost; using Newtonsoft.Json; namespace EasyPostExamples { public class Examples { public static async Task Main() { var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY")); EasyPost.Parameters.Shipment.All parameters = new() { PageSize = 5 }; EasyPost.Models.API.ShipmentCollection shipmentCollection = await client.Shipment.All(parameters); Console.WriteLine(JsonConvert.SerializeObject(shipmentCollection, Formatting.Indented)); } } } ``` #### Node.js ```javascript const EasyPostClient = require('@easypost/api'); const client = new EasyPostClient('EASYPOST_API_KEY'); (async () => { const shipments = await client.Shipment.all({ page_size: 5, }); console.log(shipments); })(); ``` #### PHP ```php shipment->all([ 'page_size' => 5, ]); echo $shipments; ``` #### Python ```python import easypost client = easypost.EasyPostClient("EASYPOST_API_KEY") shipments = client.shipment.all( page_size=5, ) print(shipments) ``` #### Ruby ```ruby require 'easypost' client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY') shipments = client.shipment.all( page_size: 5, ) puts shipments ``` A list of all `Shipment` objects associated with the given `API Key` can also be retrieved. See the Pagination section of our docs for more details on retrieving all records when multiple pages are available. {/* END: Retrieve all Shipments */} --- ## Retrieve a Shipment ### Example: GET /shipments/:id #### cURL ```shell curl -X GET https://api.easypost.com/v2/shipments/shp_... \ -u "EASYPOST_API_KEY": ``` #### Go ```go package example import ( "fmt" "github.com/EasyPost/easypost-go/v5" ) func retrieve() { client := easypost.New("EASYPOST_API_KEY") shipment, _ := client.GetShipment("shp_...") fmt.Println(shipment) } ``` #### Java ```java package shipments; import com.easypost.exception.EasyPostException; import com.easypost.model.Shipment; import com.easypost.service.EasyPostClient; public class Retrieve { public static void main(String[] args) throws EasyPostException { EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY"); Shipment shipment = client.shipment.retrieve("shp_..."); System.out.println(shipment); } } ``` #### C# ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using EasyPost; using Newtonsoft.Json; namespace EasyPostExamples { public class Examples { public static async Task Main() { var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY")); EasyPost.Models.API.Shipment shipment = await client.Shipment.Retrieve("shp_..."); Console.WriteLine(JsonConvert.SerializeObject(shipment, Formatting.Indented)); } } } ``` #### Node.js ```javascript const EasyPostClient = require('@easypost/api'); const client = new EasyPostClient('EASYPOST_API_KEY'); (async () => { const shipment = await client.Shipment.retrieve('shp_...'); console.log(shipment); })(); ``` #### PHP ```php shipment->retrieve('shp_...'); echo $shipment; ``` #### Python ```python import easypost client = easypost.EasyPostClient("EASYPOST_API_KEY") shipment = client.shipment.retrieve("shp_...") print(shipment) ``` #### Ruby ```ruby require 'easypost' client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY') shipment = client.shipment.retrieve('shp_...') puts shipment ``` A `Shipment` can be retrieved by either its `id` or `reference`. However it is recommended to use EasyPost's provided identifiers because uniqueness on `reference` is not enforced. {/* END: Retrieve a Shipment */} --- ## Converting the Label format of a Shipment ### Example: GET /shipments/:id/label #### cURL ```shell curl -X GET https://api.easypost.com/v2/shipments/shp_... \ -u "EASYPOST_API_KEY": ``` #### Go ```go package example import ( "fmt" "github.com/EasyPost/easypost-go/v5" ) func retrieve() { client := easypost.New("EASYPOST_API_KEY") shipment, _ := client.GetShipment("shp_...") fmt.Println(shipment) } ``` #### Java ```java package shipments; import com.easypost.exception.EasyPostException; import com.easypost.model.Shipment; import com.easypost.service.EasyPostClient; public class Retrieve { public static void main(String[] args) throws EasyPostException { EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY"); Shipment shipment = client.shipment.retrieve("shp_..."); System.out.println(shipment); } } ``` #### C# ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using EasyPost; using Newtonsoft.Json; namespace EasyPostExamples { public class Examples { public static async Task Main() { var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY")); EasyPost.Models.API.Shipment shipment = await client.Shipment.Retrieve("shp_..."); Console.WriteLine(JsonConvert.SerializeObject(shipment, Formatting.Indented)); } } } ``` #### Node.js ```javascript const EasyPostClient = require('@easypost/api'); const client = new EasyPostClient('EASYPOST_API_KEY'); (async () => { const shipment = await client.Shipment.retrieve('shp_...'); console.log(shipment); })(); ``` #### PHP ```php shipment->retrieve('shp_...'); echo $shipment; ``` #### Python ```python import easypost client = easypost.EasyPostClient("EASYPOST_API_KEY") shipment = client.shipment.retrieve("shp_...") print(shipment) ``` #### Ruby ```ruby require 'easypost' client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY') shipment = client.shipment.retrieve('shp_...') puts shipment ``` A `Shipment`'s `PostageLabel` can be converted from PNG to other formats. To convert a `PostageLabel`, the original must be a PNG. Converting labels works best when they are 4x6 labels converted from PNG to ZPL. {/* END: Converting the Label format of a Shipment */}