Sign in
latestOpenAPI 3.0.0Proprietary2026-08-22131410675.6 KB

8d8a7cf79204

shipments

Update shipment by ID

Update a shipment object based on its ID

put/v1/shipments/{shipment_id}

Request body

shipment_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

carrier_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

service_codestring

A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.

shipping_rule_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

external_order_idstring nullable

ID that the Order Source assigned

external_shipment_idstring nullable

A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.

Warning: The external_shipment_id is limited to 50 characters. Any additional characters will be truncated.

shipment_numberstring nullable

A non-unique user-defined number used to identify a shipment. If undefined, this will match the external_shipment_id of the shipment.

Warning: The shipment_number is limited to 50 characters. Any additional characters will be truncated.

ship_datestring date-time

An ISO 8601 string that represents a date, but not a specific time. The value may contain a time component, but it will be set to 00:00:00 UTC by ShipEngine.

created_atstring date-time

An ISO 8601 string that represents a date and time.

modified_atstring date-time

An ISO 8601 string that represents a date and time.

shipment_status'pending' | 'processing' | 'label_purchased' | 'cancelled'

The possible shipment status values

warehouse_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

is_returnboolean nullable

An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.

confirmation'none' | 'delivery' | 'signature' | 'adult_signature' | 'adult_signature_restricted_delivery' | 'direct_signature' | 'delivery_mailed' | 'verbal_confirmation' | 'delivery_code' | 'age_verification_16_plus'

The possible delivery confirmation values

insurance_provider'none' | 'shipsurance' | 'parcelguard' | 'xcover' | 'carrier' | 'third_party'

The possible insurance provider values

order_source_code'amazon_ca' | 'amazon_us' | 'brightpearl' | 'channel_advisor' | 'cratejoy' | 'ebay' | 'etsy' | 'jane' | 'groupon_goods' | 'magento' | 'paypal' | 'seller_active' | 'shopify' | 'stitch_labs' | 'squarespace' | 'three_dcart' | 'tophatter' | 'walmart' | 'woo_commerce' | 'volusion'

The order sources that are supported by ShipEngine

comparison_rate_typestring nullable

Calculate a rate for this shipment with the requested carrier using a ratecard that differs from the default. Only supported for UPS and USPS.

zoneinteger nullable

Certain carriers base their rates off of custom zones that vary depending upon the ship_to and ship_from location

validate_address'no_validation' | 'validate_only' | 'validate_and_clean'

The possible validate address values

Example request

{
  "shipment_id": "se-28529731",
  "carrier_id": "se-28529731",
  "service_code": "usps_first_class_mail",
  "shipping_rule_id": "se-28529731",
  "items": [
    {
      "asin": "B00005N5PF"
    }
  ],
  "ship_date": "2018-09-23T00:00:00.000Z",
  "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",
    "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",
    "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",
    "geolocation": [
      {
        "type": "what3words",
        "value": "cats.with.thumbs"
      }
    ]
  },
  "customs": {
    "terms_of_trade_code": "ddp",
    "contents": "gift",
    "non_delivery": "return_to_sender"
  },
  "advanced_options": {
    "bill_to_country_code": "CA",
    "freight_class": "77.5",
    "movement_indicator": "c2c",
    "license_number": "514785",
    "invoice_number": "IOC56888",
    "certificate_number": "784515",
    "fragile": true,
    "delivery_as_addressed": true,
    "return_after_first_attempt": true,
    "netstamps_options": {
      "row": 1,
      "column": 1
    }
  },
  "tags": [
    {
      "tag_id": 8712,
      "name": "Fragile",
      "color": "#FF0000"
    }
  ],
  "packages": [
    {
      "shipment_package_id": "se-28529731",
      "package_id": "se-28529731",
      "package_code": "small_flat_rate_box",
      "content_description": "Hand knitted wool socks",
      "products": [
        {
          "harmonized_tariff_code": "3926.1",
          "country_of_origin": "CA",
          "vat_rate": 0.2,
          "manufacturer_product_id": "012345678905",
          "manufacturer_ns_product_id": "MY-SKU-12345",
          "cpsc_certificates": [
            {
              "certifier_id": "CERT-12345",
              "certificate_version_id": "v1.0"
            }
          ]
        }
      ]
    }
  ],
  "comparison_rate_type": "retail",
  "zone": 6
}

Response

The request was a success.

shipment_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

carrier_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

service_codestring

A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.

shipping_rule_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

external_order_idstring nullable

ID that the Order Source assigned

external_shipment_idstring nullable

A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.

Warning: The external_shipment_id is limited to 50 characters. Any additional characters will be truncated.

shipment_numberstring nullable

A non-unique user-defined number used to identify a shipment. If undefined, this will match the external_shipment_id of the shipment.

Warning: The shipment_number is limited to 50 characters. Any additional characters will be truncated.

ship_datestring date-time

An ISO 8601 string that represents a date, but not a specific time. The value may contain a time component, but it will be set to 00:00:00 UTC by ShipEngine.

created_atstring date-time

An ISO 8601 string that represents a date and time.

modified_atstring date-time

An ISO 8601 string that represents a date and time.

shipment_status'pending' | 'processing' | 'label_purchased' | 'cancelled'

The possible shipment status values

warehouse_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

is_returnboolean nullable

An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.

confirmation'none' | 'delivery' | 'signature' | 'adult_signature' | 'adult_signature_restricted_delivery' | 'direct_signature' | 'delivery_mailed' | 'verbal_confirmation' | 'delivery_code' | 'age_verification_16_plus'

The possible delivery confirmation values

insurance_provider'none' | 'shipsurance' | 'parcelguard' | 'xcover' | 'carrier' | 'third_party'

The possible insurance provider values

order_source_code'amazon_ca' | 'amazon_us' | 'brightpearl' | 'channel_advisor' | 'cratejoy' | 'ebay' | 'etsy' | 'jane' | 'groupon_goods' | 'magento' | 'paypal' | 'seller_active' | 'shopify' | 'stitch_labs' | 'squarespace' | 'three_dcart' | 'tophatter' | 'walmart' | 'woo_commerce' | 'volusion'

The order sources that are supported by ShipEngine

comparison_rate_typestring nullable

Calculate a rate for this shipment with the requested carrier using a ratecard that differs from the default. Only supported for UPS and USPS.

zoneinteger nullable

Certain carriers base their rates off of custom zones that vary depending upon the ship_to and ship_from location

errorsstring[]

An array of errors that occurred while creating shipment.

Example response

{
  "shipment_id": "se-28529731",
  "carrier_id": "se-28529731",
  "service_code": "usps_first_class_mail",
  "shipping_rule_id": "se-28529731",
  "items": [
    {
      "asin": "B00005N5PF"
    }
  ],
  "ship_date": "2018-09-23T00:00:00.000Z",
  "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",
    "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",
    "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",
    "geolocation": [
      {
        "type": "what3words",
        "value": "cats.with.thumbs"
      }
    ]
  },
  "customs": {
    "terms_of_trade_code": "ddp",
    "contents": "gift",
    "non_delivery": "return_to_sender"
  },
  "advanced_options": {
    "bill_to_country_code": "CA",
    "freight_class": "77.5",
    "movement_indicator": "c2c",
    "license_number": "514785",
    "invoice_number": "IOC56888",
    "certificate_number": "784515",
    "fragile": true,
    "delivery_as_addressed": true,
    "return_after_first_attempt": true,
    "netstamps_options": {
      "row": 1,
      "column": 1
    }
  },
  "tags": [
    {
      "tag_id": 8712,
      "name": "Fragile",
      "color": "#FF0000"
    }
  ],
  "packages": [
    {
      "shipment_package_id": "se-28529731",
      "package_id": "se-28529731",
      "package_code": "small_flat_rate_box",
      "content_description": "Hand knitted wool socks",
      "products": [
        {
          "harmonized_tariff_code": "3926.1",
          "country_of_origin": "CA",
          "vat_rate": 0.2,
          "manufacturer_product_id": "012345678905",
          "manufacturer_ns_product_id": "MY-SKU-12345",
          "cpsc_certificates": [
            {
              "certifier_id": "CERT-12345",
              "certificate_version_id": "v1.0"
            }
          ]
        }
      ]
    }
  ],
  "comparison_rate_type": "retail",
  "zone": 6,
  "errors": [
    "Parameter value '100000000.00' 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"
      }
    ]
  }
}