shipments
Create shipments
<aside class="access" aria-label="Endpoint access"> <table class="access__table"> <thead> <tr> <th class="access__table-header">Products</th> <th class="access__table-header">Plans</th> </tr> </thead> <tbody> <tr> <td class="access__table-cell access__product"> <img class="access__logo" src="/static/logos/shipstation-api-logo.svg" alt="ShipStation API Logo" loading="lazy" decoding="async"/> <div class="access__sub">Formerly ShipEngine</div> </td> <td class="access__table-cell access__plans"> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-free.md" class="access__plan">Free</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Advanced</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Enterprise</a> </td> </tr> <tr> <td class="access__table-cell"> <img class="access__logo" src="/static/logos/shipstation-logo.svg" alt="ShipStation Logo" loading="lazy" decoding="async"/> </td> <td class="access__table-cell access__plans"> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Free</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Starter</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Standard</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Premium</a> </td> </tr> </tbody> </table> <footer class="access__footer"> <a class="access__help" href="/apis/@shipstation-v2/docs/getting-started/products-and-plans.md"> Learn about products and plans <img src="/static/icons/external-link.svg" alt="External Link Icon" style="width: 16px;" loading="lazy" decoding="async"/> </a> </footer> </aside>Create one or more shipments
post/v2/shipments
Request body
Example request
{
"shipments": [
{
"external_shipment_id": "1751939189",
"carrier_id": "se-28529731",
"create_sales_order": true,
"store_id": "1582173",
"notes_from_buyer": "I am a note from the buyer",
"notes_to_buyer": "Thank you for your order!",
"notes_for_gift": "I am a gift note",
"internal_notes": "Check packaging before shipping",
"is_gift": true,
"display_scheme": "paperless",
"requested_shipment_service": "usps_priority_mail",
"deliver_by_date": "2025-01-20T00:00:00.000Z",
"assigned_user": "a2df9fa5-b7ee-467f-be4e-9c660542c187",
"amount_paid": {
"amount": 12
},
"shipping_paid": {
"amount": 12
},
"tax_paid": {
"amount": 12
},
"ship_to": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"instructions": "any instruction",
"geolocation": [
{
"type": "what3words",
"value": "cats.with.thumbs"
}
]
},
"ship_from": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"instructions": "any instructions",
"geolocation": [
{
"type": "what3words",
"value": "cats.with.thumbs"
}
]
},
"warehouse_id": "se-28529731",
"items": [
{
"name": "box",
"sales_order_id": "12345",
"sales_order_item_id": "1234556",
"quantity": 1,
"sku": "sku-1234",
"bundle_sku": "bundle-123",
"external_order_id": "123445",
"external_order_item_id": "12",
"asin": "B00005N5PF",
"item_id": "1402291169813",
"allocation_status": "allocated",
"image_url": "https://example.com/image.jpg",
"weight": {
"value": 23
},
"unit_price": 88,
"tax_amount": 5.5,
"shipping_amount": 10,
"inventory_location": "warehouse-a",
"options": [
{
"name": "Color",
"value": "Red"
}
],
"product_id": "10408926",
"fullfilment_sku": "fulfill-123",
"upc": "123456789012"
}
],
"packages": [
{
"shipment_package_id": "se-28529731",
"package_id": "se-28529731",
"package_code": "small_flat_rate_box",
"package_name": "Flat Rate Envelope",
"weight": {
"value": 23
},
"dimensions": {
"length": 2,
"width": 2,
"height": 1
},
"insured_value": {
"amount": 12
},
"label_messages": {
"reference1": "Reference",
"reference2": "Reference 2",
"reference3": "Reference 3"
},
"external_package_id": "se-1234545",
"content_description": "Hand knitted wool socks",
"products": [
{
"description": "a minimum description",
"quantity": 1,
"value": {
"amount": 12
},
"weight": {
"value": 23
},
"harmonized_tariff_code": "3926.10",
"country_of_origin": "CA",
"unit_of_measure": "pound",
"sku": "sku-1223344",
"sku_description": "this is a description",
"mid_code": "GBCOM15BRI",
"product_url": "https://myproduct.com",
"vat_rate": 0.2,
"dangerous_goods": [
{
"id_number": "1234r1",
"shipping_name": "things with dangerous goods",
"technical_name": "chloric acid",
"product_class": "1987",
"product_class_subsidiary": "1987",
"packaging_group": "ii",
"dangerous_amount": {
"amount": 12,
"unit": "GBP"
},
"quantity": 1,
"packaging_instruction": "Packaging materials and containers that are in contact with food products must comply with the provisions established by Regulation ",
"packaging_instruction_section": "section_1",
"packaging_type": "X",
"transport_mean": "ground",
"transport_category": "6.1",
"regulation_authority": "AEAT",
"regulation_level": "excepted_quantity",
"tunnel_code": "all",
"additional_description": "any description"
}
],
"manufacturer_product_id": "012345678905",
"manufacturer_ns_product_id": "MY-SKU-12345",
"cpsc_certificates": [
{
"certifier_id": "CERT-12345",
"certificate_version_id": "v1.0"
}
]
}
]
}
]
}
]
}Response
The request was a success.
Example response
{
"shipments": [
{
"shipment_id": "se-28529731",
"carrier_id": "se-28529731",
"service_code": "usps_first_class_mail",
"requested_shipment_service": "usps_priority_mail",
"external_order_id": "1232434",
"hold_until_date": "2025-01-15T00:00:00.000Z",
"ship_by_date": "2025-01-15T00:00:00.000Z",
"deliver_by_date": "2025-01-20T00:00:00.000Z",
"retail_rate": {
"amount": 12
},
"store_id": "se-28529731",
"items": [
{
"name": "box",
"sales_order_id": "12345",
"sales_order_item_id": "1234556",
"quantity": 1,
"sku": "sku-1234",
"bundle_sku": "bundle-123",
"external_order_id": "123445",
"external_order_item_id": "12",
"asin": "B00005N5PF",
"item_id": "1402291169813",
"allocation_status": "allocated",
"image_url": "https://example.com/image.jpg",
"weight": {
"value": 23
},
"unit_price": 88,
"tax_amount": 5.5,
"shipping_amount": 10,
"inventory_location": "warehouse-a",
"options": [
{
"name": "Color",
"value": "Red"
}
],
"product_id": "10408926",
"fullfilment_sku": "fulfill-123",
"upc": "123456789012"
}
],
"notes_from_buyer": "Please handle with care",
"notes_to_buyer": "Thank you for your order!",
"notes_for_gift": "Happy Birthday!",
"internal_notes": "Check packaging before shipping",
"is_gift": true,
"assigned_user": "user@example.com",
"amount_paid": {
"amount": 12
},
"shipping_paid": {
"amount": 12
},
"tax_paid": {
"amount": 12
},
"zone": 1,
"display_scheme": "label",
"tax_identifiers": [
{
"issuing_authority": "US",
"value": "value"
}
],
"external_shipment_id": "1234556",
"shipment_number": "10001",
"ship_date": "2018-09-23T00:00:00Z",
"created_at": "2018-09-23T15:00:00.000Z",
"modified_at": "2018-09-23T15:00:00.000Z",
"ship_to": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"instructions": "any instruction",
"geolocation": [
{
"type": "what3words",
"value": "cats.with.thumbs"
}
]
},
"ship_from": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"instructions": "any instructions",
"geolocation": [
{
"type": "what3words",
"value": "cats.with.thumbs"
}
]
},
"warehouse_id": "se-28529731",
"return_to": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"instructions": "any instructions",
"geolocation": [
{
"type": "what3words",
"value": "cats.with.thumbs"
}
]
},
"is_return": true,
"customs": {
"terms_of_trade_code": "ddp",
"contents": "gift",
"non_delivery": "return_to_sender"
},
"advanced_options": {
"bill_to_account": "123456789",
"bill_to_country_code": "CA",
"bill_to_postal_code": "28005",
"contains_alcohol": true,
"delivered_duty_paid": true,
"dry_ice": true,
"dry_ice_weight": {
"value": 23
},
"non_machinable": true,
"saturday_delivery": true,
"fedex_freight": {
"shipper_load_and_count": "shipper_load_and_count",
"booking_confirmation": "today"
},
"use_ups_ground_freight_pricing": true,
"freight_class": "77.5",
"custom_field1": "custom field 1",
"custom_field2": "custom field 2",
"custom_field3": "custom field 3",
"additional_handling": true,
"shipper_release": true,
"collect_on_delivery": {
"payment_amount": {
"amount": 12
}
},
"third_party_consignee": true,
"dangerous_goods": true,
"dangerous_goods_contact": {
"name": "Michael Robinson",
"phone": "123456578789"
},
"movement_indicator": "b2b",
"windsor_framework_details": {
"movement_indicator": "b2b",
"not_at_risk": true
},
"ancillary_endorsements_option": "forward",
"return_pickup_attempts": 3,
"netstamps_options": {
"row": 1,
"column": 1
}
},
"tags": [
{
"name": "Fragile"
}
],
"packages": [
{
"shipment_package_id": "se-28529731",
"package_id": "se-28529731",
"package_code": "small_flat_rate_box",
"package_name": "Flat Rate Envelope",
"weight": {
"value": 23
},
"dimensions": {
"length": 2,
"width": 2,
"height": 1
},
"insured_value": {
"amount": 12
},
"label_messages": {
"reference1": "Reference",
"reference2": "Reference 2",
"reference3": "Reference 3"
},
"external_package_id": "se-1234545",
"content_description": "Hand knitted wool socks",
"products": [
{
"description": "a minimum description",
"quantity": 1,
"value": {
"amount": 12
},
"weight": {
"value": 23
},
"harmonized_tariff_code": "3926.10",
"country_of_origin": "CA",
"unit_of_measure": "pound",
"sku": "sku-1223344",
"sku_description": "this is a description",
"mid_code": "GBCOM15BRI",
"product_url": "https://myproduct.com",
"vat_rate": 0.2,
"dangerous_goods": [
{
"id_number": "1234r1",
"shipping_name": "things with dangerous goods",
"technical_name": "chloric acid",
"product_class": "1987",
"product_class_subsidiary": "1987",
"packaging_group": "ii",
"dangerous_amount": {
"amount": 12,
"unit": "GBP"
},
"quantity": 1,
"packaging_instruction": "Packaging materials and containers that are in contact with food products must comply with the provisions established by Regulation ",
"packaging_instruction_section": "section_1",
"packaging_type": "X",
"transport_mean": "ground",
"transport_category": "6.1",
"regulation_authority": "AEAT",
"regulation_level": "excepted_quantity",
"tunnel_code": "all",
"additional_description": "any description"
}
],
"manufacturer_product_id": "012345678905",
"manufacturer_ns_product_id": "MY-SKU-12345",
"cpsc_certificates": [
{
"certifier_id": "CERT-12345",
"certificate_version_id": "v1.0"
}
]
}
]
}
],
"total_weight": {
"value": 3
},
"comparison_rate_type": "retail",
"errors": [
"Parameter value is out of range."
],
"address_validation": {
"original_address": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA"
},
"matched_address": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA"
},
"messages": [
{
"message": "Invalid Postal Code"
}
]
}
}
]
}