Schedule a Carrier Pickup

With ShipEngine, you can request a carrier pickup at your office, warehouse, or other location. This allows the carrier to come and get your packages so you don't have to drop them off in a drop box or store. Some carriers charge a fee for this service depending on the pickup type and frequency, so check with your carrier to ensure you don't incur any unexpected charges. You can take advantage of this via our v1/pickups endpoint for our supported carriers.

Supported Carriers

  • UPS
  • USPS
  • DHL Express

Carrier Pickup Information

UPS

UPS pickup times can vary depending on service and pickup location. Please contact your UPS sales representative to get information specific to your account.

Examples

Schedule a Pickup

To schedule a pickup, you'll need to send us a list of the label ids that you would like picked up. All the labels must be from the same carrier and have the same warehouse id. The pickup location will be the ship from or warehouse id you used when you created the label.

Tip

Pickup Window

The pickup_window range must be specified as a valid ISO 8601 string.

POST /v1/pickups HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
  "label_ids": [
    "se-28529731"
  ],
  "contact_details": {
    "name": "John Stuckey",
    "email": "[email protected]",
    "phone": "6625905259"
  },
  "pickup_notes": "Please knock, doorbell is broken.",
  "pickup_window": {
    "start_at": "2019-11-11T15:00:00.000Z",
    "end_at": "2019-11-11T18:00:00.000Z"
  }
}
{
  "pickup_id": "pik_3YcKU5zdtJuCqoeNwyqqbW",
  "label_ids": [
    "se-28529731"
  ],
  "created_at": "2018-09-23T15:00:00.000Z",
  "cancelled_at": "2018-09-23T15:00:00.000Z",
  "carrier_id": "se-28529731",
  "warehouse_id": "se-28529731",
  "confirmation_number": "292513CL4A3",
  "contact_details": {
    "name": "string",
    "email": "[email protected]",
    "phone": "strings"
  },
  "pickup_notes": "string",
  "pickup_window": [{
    "start_at": "2019-11-11T15:00:00.000Z",
    "end_at": "2018-11-11T15:00:00.000Z"
  }]
}

Cancel a Pickup

If you would like to cancel a pickup that you've previously scheduled then call the /v1/pickups/:pickup_id endpoint with the id of the pickup you would like to cancel. Note that some carriers have rules around how close to the pickup window a pickup can be cancelled.

DELETE /v1/pickups/pik_3YcKU5zdtJuCqoeNwyqqbW HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__

The response includes the ID of the cancelled pickup.

{
  "pickup_id": "pik_3YcKU5zdtJuCqoeNwyqqbW"
}

List Your Pickups

You may also list all your pickups, including those that have been cancelled or have already been picked up, by using the /v1/pickups endpoint. This is the same endpoint you used to schedule the pickups, but you will use an HTTP GET rather than an HTTP POST to list your pickups.

GET /v1/pickups HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "pickups": [
    {
      "pickup_id": "pik_EzSSBdj2bgrK8tfNAABP9v",
      "carrier_id": "se-96770",
      "warehouse_id": null,
      "confirmation_number": "29J62276GH7",
      "label_ids": [
        "se-963397"
      ],
      "contact_details": {
        "name": "John Stuckey",
        "email": "[email protected]",
        "phone": "6625905259"
      },
      "pickup_notes": "Please knock, doorbell is broken.",
      "pickup_windows": [
        {
          "start_at": "2020-06-26T11:00:00Z",
          "end_at": "2020-06-26T17:00:00Z"
        }
      ],
      "pickup_address": {
        "name": "John Doe",
        "phone": "555-555-5555",
        "company_name": "Example Corp",
        "address_line1": "4009 Marathon Blvd",
        "address_line2": null,
        "address_line3": null,
        "city_locality": "Austin",
        "state_province": "TX",
        "postal_code": "78756",
        "country_code": "US",
        "address_residential_indicator": "unknown"
      },
      "created_at": "2020-06-24T13:19:15.75Z",
      "canceled_at": null
    }
  ],
  "total": 3,
  "page": 3,
  "pages": 3,
  "links": {
    "first": {
      "href": "https://api.shipengine.com/v1/pickups?page=1&page_size=1"
    },
    "last": {
      "href": "https://api.shipengine.com/v1/pickups?page=3&page_size=1"
    },
    "prev": {
      "href": "https://api.shipengine.com/v1/pickups?page=2&page_size=1"
    },
    "next": {}
  }
}

View a Specific Pickup

You can get information about a specific pickup by calling /v1/pickups/:pickup_id.

GET /v1/pickups/pik_EzSSBdj2bgrK8tfNAABP9v HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "pickup_id": "pik_EzSSBdj2bgrK8tfNAABP9v",
  "carrier_id": "se-96770",
  "warehouse_id": null,
  "confirmation_number": "29J62276GH7",
  "label_ids": [
    "se-963397"
  ],
  "contact_details": {
    "name": "John Stuckey",
    "email": "[email protected]",
    "phone": "6625905259"
  },
  "pickup_notes": "Please knock, doorbell is broken.",
  "pickup_windows": [
    {
      "start_at": "2020-06-26T11:00:00Z",
      "end_at": "2020-06-26T17:00:00Z"
    }
  ],
  "pickup_address": {
    "name": "John Doe",
    "phone": "555-555-5555",
    "company_name": "Example Corp",
    "address_line1": "4009 Marathon Blvd",
    "address_line2": null,
    "address_line3": null,
    "city_locality": "Austin",
    "state_province": "TX",
    "postal_code": "78756",
    "country_code": "US",
    "address_residential_indicator": "unknown"
  },
  "created_at": "2020-06-24T13:19:15.75Z",
  "canceled_at": null
}