{"templateId":"markdown","versions":[{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/shipstation-v2/docs/shipping/using-custom-packages","default":true,"active":false,"folderId":"58c9a61d"},{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/shipping/using-custom-packages","default":false,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/shipping/using-custom-packages","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Using Custom Packages","keywords":"shipping, labels, shipstation, documentation, api","siteUrl":"https://docs.shipstation.com","lang":"en-US","llmstxt":{"hide":false,"title":"ShipStation API LLM Docs","description":"Find links and references to all markdown documentation for use with LLMs","excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"using-custom-packages","__idx":0},"children":["Using Custom Packages"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/shipping/custom-package-types"},"children":["defined your custom packages"]},", you can then use either the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package_id"]}," or the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package_code"]}," in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipments"]}," object when creating your shipment or purchasing a label."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["NOTE:"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"package_id-vs-package_code","__idx":1},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package_id"]}," vs ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package_code"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When creating or updating shipments, you can provide either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package_code"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package_id"]},". If both are included, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package_code"]}," will take precedence. When getting rates or labels, only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package_code"]}," is supported."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-request--response","__idx":2},"children":["Example Request & Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example, we replace the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dimensions"]}," object with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package_code"]}," property in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["packages"]}," object."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["POST /v1/shipments"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/shipments HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n{\n  \"shipments\": [\n    {\n      \"service_code\": \"usps_priority_mail\",\n      \"shipment_status\": \"pending\",\n      \"ship_to\": {\n        \"name\": \"Amanda Miller\",\n        \"phone\": \"555-555-5555\",\n        \"address_line1\": \"525 S Winchester Blvd\",\n        \"city_locality\": \"San Jose\",\n        \"state_province\": \"CA\",\n        \"postal_code\": \"95128\",\n        \"country_code\": \"US\",\n        \"address_residential_indicator\": \"yes\"\n      },\n      \"ship_from\": {\n        \"company_name\": \"Example Corp.\",\n        \"name\": \"John Doe\",\n        \"phone\": \"111-111-1111\",\n        \"address_line1\": \"4009 Marathon Blvd\",\n        \"address_line2\": \"Suite 300\",\n        \"city_locality\": \"Austin\",\n        \"state_province\": \"TX\",\n        \"postal_code\": \"78756\",\n        \"country_code\": \"US\",\n        \"address_residential_indicator\": \"no\"\n      },\n      \"confirmation\": \"none\",\n      \"advanced_options\": {},\n      \"insurance_provider\": \"none\",\n      \"tags\": [],\n      \"total_weight\": {\n        \"value\": 10.0,\n        \"unit\": \"ounce\"\n      },\n      \"packages\": [\n        {\n          \"package_code\": \"custom_laptop_box\",\n          \"weight\": {\n            \"value\": 10.0,\n            \"unit\": \"ounce\"\n          }\n        }\n      ]\n    }\n  ]\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the response, you'll see the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package_code"]}," property in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["packages"]}," object (in addition to all its included properties), which indicates that it worked!"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"has_errors\": false,\n  \"shipments\": [\n    {\n      \"errors\": null,\n      \"address_validation\": {\n        \"status\": \"verified\",\n        \"original_address\": {\n          \"name\": \"Amanda Miller\",\n          \"phone\": \"555-555-5555\",\n          \"address_line1\": \"525 S Winchester Blvd\",\n          \"city_locality\": \"San Jose\",\n          \"state_province\": \"CA\",\n          \"postal_code\": \"95128\",\n          \"country_code\": \"US\",\n          \"address_residential_indicator\": \"yes\"\n        },\n        \"matched_address\": {\n          \"name\": \"AMANDA MILLER\",\n          \"phone\": \"555-555-5555\",\n          \"address_line1\": \"525 S WINCHESTER BLVD\",\n          \"city_locality\": \"SAN JOSE\",\n          \"state_province\": \"CA\",\n          \"postal_code\": \"95128\",\n          \"country_code\": \"US\",\n          \"address_residential_indicator\": \"yes\"\n        },\n        \"messages\": []\n      },\n      \"shipment_id\": \"se-41838065\",\n      \"carrier_id\": \"se-123890\",\n      \"service_code\": \"usps_priority_mail\",\n      \"external_shipment_id\": null,\n      \"ship_date\": \"2019-07-25T05:00:00.000Z\",\n      \"created_at\": \"2019-07-25T15:24:46.657Z\",\n      \"modified_at\": \"2019-07-25T15:24:46.657Z\",\n      \"shipment_status\": \"pending\",\n      \"ship_to\": {\n        \"name\": \"Amanda Miller\",\n        \"phone\": \"555-555-5555\",\n        \"address_line1\": \"525 S Winchester Blvd\",\n        \"city_locality\": \"San Jose\",\n        \"state_province\": \"CA\",\n        \"postal_code\": \"95128\",\n        \"country_code\": \"US\",\n        \"address_residential_indicator\": \"yes\"\n      },\n      \"ship_from\": {\n        \"company_name\": \"Example Corp.\",\n        \"name\": \"John Doe\",\n        \"phone\": \"111-111-1111\",\n        \"address_line1\": \"4009 Marathon Blvd\",\n        \"address_line2\": \"Suite 300\",\n        \"city_locality\": \"Austin\",\n        \"state_province\": \"TX\",\n        \"postal_code\": \"78756\",\n        \"country_code\": \"US\",\n        \"address_residential_indicator\": \"no\"\n      },\n      \"warehouse_id\": null,\n      \"return_to\": {\n        \"company_name\": \"Example Corp.\",\n        \"name\": \"John Doe\",\n        \"phone\": \"111-111-1111\",\n        \"address_line1\": \"4009 Marathon Blvd\",\n        \"address_line2\": \"Suite 300\",\n        \"city_locality\": \"Austin\",\n        \"state_province\": \"TX\",\n        \"postal_code\": \"78756\",\n        \"country_code\": \"US\",\n        \"address_residential_indicator\": \"no\"\n      },\n      \"confirmation\": \"none\",\n      \"advanced_options\": {\n        \"bill_to_account\": null,\n        \"bill_to_country_code\": null,\n        \"bill_to_party\": null,\n        \"bill_to_postal_code\": null,\n        \"contains_alcohol\": false,\n        \"custom_field1\": null,\n        \"custom_field2\": null,\n        \"custom_field3\": null,\n        \"non_machinable\": false,\n        \"saturday_delivery\": false\n      },\n      \"insurance_provider\": \"none\",\n      \"tags\": [],\n      \"total_weight\": {\n        \"value\": 10.0,\n        \"unit\": \"ounce\"\n      },\n      \"packages\": [\n        {\n          \"package_code\": \"custom_laptop_box\",\n          \"weight\": {\n            \"value\": 10.0,\n            \"unit\": \"ounce\"\n          },\n          \"dimensions\": {\n            \"unit\": \"inch\",\n            \"length\": 15.00,\n            \"width\": 20.00,\n            \"height\": 5.00\n          },\n          \"insured_value\": {\n            \"currency\": \"usd\",\n            \"amount\": 0.0\n          }\n        }\n      ]\n    }\n  ]\n}\n","lang":"json"},"children":[]}]},"headings":[{"value":"Using Custom Packages","id":"using-custom-packages","depth":1},{"value":"package_id vs package_code","id":"package_id-vs-package_code","depth":3},{"value":"Example Request & Response","id":"example-request--response","depth":2}],"frontmatter":{"seo":{"title":"Using Custom Packages"}},"lastModified":"2026-04-08T10:47:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/shipengine/docs/shipping/using-custom-packages","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}