Ship From a Warehouse

Learn how to leverage warehouses in ShipEngine®.

You likely have one or more warehouse locations that you frequently ship from, in which case it would be annoying to have to specify the ship_from and return_to addresses on every shipment. The solution is to Create a Warehouse, then you can simply pass the warehouse_id instead.

Using warehouses also allows you to Create Manifests of everything you're shipping from each warehouse.

Example

The following example demonstrates how to create a shipment using a warehouse_id instead of a ship_from address. Other than that, it's the same as the normal Create a Shipment workflow.

POST /v1/shipments HTTP/1.1
host: $apiHost$
api-key: $apiAuthKey$
content-type: application/json
content-length: 1054

{
  "shipments": [
    {
      "service_code": "usps_priority_mail",
      "ship_to": {
        "name": "Mickey and Minnie Mouse",
        "phone": "714-781-4565",
        "company_name": "The Walt Disney Company",
        "address_line1": "500 South Buena Vista Street",
        "city_locality": "Burbank",
        "state_province": "CA",
        "postal_code": "91521",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "warehouse_id": "se-277331",
      "packages": [
        {
          "weight": {
            "value": 1.0,
            "unit": "ounce"
          }
        }
      ]
    }
  ]
}
curl $apiUrl$/v1/shipments 
  -X POST \
  -H "content-type: application/json" \
  -H "api-key: #apiAuthKey#" \
  -d '
{
  "shipments": [
    {
      "service_code": "usps_priority_mail",
      "ship_to": {
        "name": "Mickey and Minnie Mouse",
        "phone": "714-781-4565",
        "company_name": "The Walt Disney Company",
        "address_line1": "500 South Buena Vista Street",
        "city_locality": "Burbank",
        "state_province": "CA",
        "postal_code": "91521",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "warehouse_id": "se-277331",
      "packages": [
        {
          "weight": {
            "value": 1.0,
            "unit": "ounce"
          }
        }
      ]
    }
  ]
}'
{
  "has_errors": false,
  "shipments": [
    {
      "errors": null,
      "address_validation": {
        "status": "verified",
        "original_address": {
          "name": "Mickey and Minnie Mouse",
          "phone": "714-781-4565",
          "company_name": "The Walt Disney Company",
          "address_line1": "500 South Buena Vista Street",
          "address_line2": null,
          "address_line3": null,
          "city_locality": "Burbank",
          "state_province": "CA",
          "postal_code": "91521",
          "country_code": "US",
          "address_residential_indicator": "no"
        },
        "matched_address": {
          "name": "MICKEY AND MINNIE MOUSE",
          "phone": "714-781-4565",
          "company_name": "THE WALT DISNEY COMPANY",
          "address_line1": "500 S BUENA VISTA ST",
          "address_line2": "",
          "address_line3": null,
          "city_locality": "BURBANK",
          "state_province": "CA",
          "postal_code": "91521-0007",
          "country_code": "US",
          "address_residential_indicator": "no"
        },
        "messages": []
      },
      "shipment_id": "se-202927168",
      "carrier_id": "se-123890",
      "service_code": "usps_priority_mail",
      "external_shipment_id": null,
      "ship_date": "2018-02-12T00:00:00Z",
      "created_at": "2018-02-13T02:17:28.5734844Z",
      "modified_at": "2018-02-13T02:17:28.5734844Z",
      "shipment_status": "pending",
      "ship_to": {
        "name": "MICKEY AND MINNIE MOUSE",
        "phone": "714-781-4565",
        "company_name": "THE WALT DISNEY COMPANY",
        "address_line1": "500 S BUENA VISTA ST",
        "address_line2": "",
        "address_line3": null,
        "city_locality": "BURBANK",
        "state_province": "CA",
        "postal_code": "91521-0007",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "ship_from": {
        "name": "Dade Murphy",
        "phone": "512-485-4282",
        "company_name": "Zero Cool",
        "address_line1": "345 Chambers Street",
        "address_line2": "Suite 100",
        "address_line3": null,
        "city_locality": "New York City",
        "state_province": "NY",
        "postal_code": "10282",
        "country_code": "US",
        "address_residential_indicator": "unknown"
      },
      "warehouse_id": "se-277331",
      "return_to": {
        "name": "Dade Murphy",
        "phone": "512-485-4282",
        "company_name": "Zero Cool Returns",
        "address_line1": "345 Chambers Street",
        "address_line2": "Suite 100",
        "address_line3": null,
        "city_locality": "New York City",
        "state_province": "NY",
        "postal_code": "10282",
        "country_code": "US",
        "address_residential_indicator": "unknown"
      },
      "confirmation": "none",
      "customs": null,
      "advanced_options": {
        "bill_to_account": null,
        "bill_to_country_code": null,
        "bill_to_party": null,
        "bill_to_postal_code": null,
        "contains_alcohol": false,
        "delivered_duty_paid": false,
        "non_machinable": false,
        "saturday_delivery": false,
        "freight_class": null,
        "custom_field1": null,
        "custom_field2": null,
        "custom_field3": null
      },
      "insurance_provider": "none",
      "tags": [],
      "packages": [
        {
          "package_code": "package",
          "weight": {
            "value": 1.0,
            "unit": "ounce"
          },
          "dimensions": {
            "unit": "inch",
            "length": 0.0,
            "width": 0.0,
            "height": 0.0
          },
          "insured_value": {
            "currency": "usd",
            "amount": 0.0
          },
          "label_messages": {
            "reference1": null,
            "reference2": null,
            "reference3": null
          }
        }
      ],
      "total_weight": {
        "value": 1.0,
        "unit": "ounce"
      }
    }
  ]
}

Overriding the Return Address

By default, specifying a warehouse_id will automatically set ship_from and return_to addresses of the shipment. But there are some scenarios where you may want to override the return address that's printed on the shipping label. ShipEngine allows you to do that by specifying a return_to address in addition to the warehouse_id.

This feature is currently only supported for Stamps.com, FedEx, and UPS. Please let us know if you need support for additional carriers.

POST /v1/shipments HTTP/1.1
host: $apiHost$
api-key: $apiAuthKey$
content-type: application/json
content-length: 1054

{
  "shipments": [
    {
      "service_code": "usps_priority_mail",
      "ship_to": {
        "name": "Mickey and Minnie Mouse",
        "phone": "714-781-4565",
        "company_name": "The Walt Disney Company",
        "address_line1": "500 South Buena Vista Street",
        "city_locality": "Burbank",
        "state_province": "CA",
        "postal_code": "91521",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "return_to": {
        "phone": "1-800-555-0000",
        "company_name": "Custom Return Co.",
        "address_line1": "100 S. First Ave",
        "city_locality": "Memphis",
        "state_province": "TN",
        "postal_code": "38109",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "warehouse_id": "se-277331",
      "packages": [
        {
          "weight": {
            "value": 1.0,
            "unit": "ounce"
          }
        }
      ]
    }
  ]
}
curl $apiUrl$/v1/shipments 
  -X POST \
  -H "content-type: application/json" \
  -H "api-key: #apiAuthKey#" \
  -d '
{
  "shipments": [
    {
      "service_code": "usps_priority_mail",
      "ship_to": {
        "name": "Mickey and Minnie Mouse",
        "phone": "714-781-4565",
        "company_name": "The Walt Disney Company",
        "address_line1": "500 South Buena Vista Street",
        "city_locality": "Burbank",
        "state_province": "CA",
        "postal_code": "91521",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "return_to": {
        "phone": "1-800-555-0000",
        "company_name": "Custom Return Co.",
        "address_line1": "100 S. First Ave",
        "city_locality": "Memphis",
        "state_province": "TN",
        "postal_code": "38109",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "warehouse_id": "se-277331",
      "packages": [
        {
          "weight": {
            "value": 1.0,
            "unit": "ounce"
          }
        }
      ]
    }
  ]
}'
{
  "has_errors": false,
  "shipments": [
    {
      "errors": null,
      "address_validation": {
        "status": "verified",
        "original_address": {
          "name": "Mickey and Minnie Mouse",
          "phone": "714-781-4565",
          "company_name": "The Walt Disney Company",
          "address_line1": "500 South Buena Vista Street",
          "address_line2": null,
          "address_line3": null,
          "city_locality": "Burbank",
          "state_province": "CA",
          "postal_code": "91521",
          "country_code": "US",
          "address_residential_indicator": "no"
        },
        "matched_address": {
          "name": "MICKEY AND MINNIE MOUSE",
          "phone": "714-781-4565",
          "company_name": "THE WALT DISNEY COMPANY",
          "address_line1": "500 S BUENA VISTA ST",
          "address_line2": "",
          "address_line3": null,
          "city_locality": "BURBANK",
          "state_province": "CA",
          "postal_code": "91521-0007",
          "country_code": "US",
          "address_residential_indicator": "no"
        },
        "messages": []
      },
      "shipment_id": "se-202927168",
      "carrier_id": "se-123890",
      "service_code": "usps_priority_mail",
      "external_shipment_id": null,
      "ship_date": "2018-02-12T00:00:00Z",
      "created_at": "2018-02-13T02:17:28.5734844Z",
      "modified_at": "2018-02-13T02:17:28.5734844Z",
      "shipment_status": "pending",
      "ship_to": {
        "name": "MICKEY AND MINNIE MOUSE",
        "phone": "714-781-4565",
        "company_name": "THE WALT DISNEY COMPANY",
        "address_line1": "500 S BUENA VISTA ST",
        "address_line2": "",
        "address_line3": null,
        "city_locality": "BURBANK",
        "state_province": "CA",
        "postal_code": "91521-0007",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "ship_from": {
        "name": "Dade Murphy",
        "phone": "512-485-4282",
        "company_name": "Zero Cool",
        "address_line1": "345 Chambers Street",
        "address_line2": "Suite 100",
        "address_line3": null,
        "city_locality": "New York City",
        "state_province": "NY",
        "postal_code": "10282",
        "country_code": "US",
        "address_residential_indicator": "unknown"
      },
      "warehouse_id": "se-277331",
      "return_to": {
        "phone": "1-800-555-0000",
        "company_name": "Custom Return Co.",
        "address_line1": "100 S. First Ave",
        "address_line2": null,
        "address_line3": null,
        "city_locality": "Memphis",
        "state_province": "TN",
        "postal_code": "38109",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "confirmation": "none",
      "customs": null,
      "advanced_options": {
        "bill_to_account": null,
        "bill_to_country_code": null,
        "bill_to_party": null,
        "bill_to_postal_code": null,
        "contains_alcohol": false,
        "delivered_duty_paid": false,
        "non_machinable": false,
        "saturday_delivery": false,
        "freight_class": null,
        "custom_field1": null,
        "custom_field2": null,
        "custom_field3": null
      },
      "insurance_provider": "none",
      "tags": [],
      "packages": [
        {
          "package_code": "package",
          "weight": {
            "value": 1.0,
            "unit": "ounce"
          },
          "dimensions": {
            "unit": "inch",
            "length": 0.0,
            "width": 0.0,
            "height": 0.0
          },
          "insured_value": {
            "currency": "usd",
            "amount": 0.0
          },
          "label_messages": {
            "reference1": null,
            "reference2": null,
            "reference3": null
          }
        }
      ],
      "total_weight": {
        "value": 1.0,
        "unit": "ounce"
      }
    }
  ]
}

Ship From a Warehouse


Learn how to leverage warehouses in ShipEngine®.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.