Schedule a Carrier Pickup

With ShipEngine, you can request a carrier pickup at your office, warehouse, or other location using the v1/pickups endpoint. 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.

Requirements

Use a carrier that supports scheduling pickups via ShipEngine.
To schedule a pickup, you'll need to include the 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.
The Pickup requests must also include:
- The contact_details object with the contact name, email, and phone properties.
- The pickup_window object with the start_at and end_at properties. The pickup_window range start_at and end_at values must be specified as valid ISO 8601 strings. All times should be submitted in UTC. If only a date is specified with no time value, then the pickup time is the entire business day.

Example Request & Response

POST /v1/pickups

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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"
  }
}

Response

The response will include a pickup_id, the associated pickup properties, the carrier's pickup window, a request_id (useful if you need to contact support to debug an issue), and an error object (if any errors occured).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "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, you can use the DELETE method with the /v1/pickups/:pickup_id endpoint. You'll need the pickup_id of the pickup you wish to cancel. Note that some carriers have rules around how close to the pickup window you can cancel a pickup.

Example Request & Response

DELETE /v1/pickups/:pickup_id

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

Response

If successful, the response includes the ID of the cancelled pickup.

1
2
3
{
  "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 the GET method rather than the POST method to list your pickups.

Example Request & Response

GET /v1/pickups

1
2
3
4
GET /v1/pickups HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
{
  "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 adding the pickup_id to the /v1/pickups/ endpoint.

Example Request & Response

GET /v1/pickups/:pickup_id

1
2
3
4
GET /v1/pickups/pik_EzSSBdj2bgrK8tfNAABP9v HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
  "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
}

Supported Carriers

This is a list of popular carriers that support the schedule pickup endpoint. This may not represent all carriers that support pickups. If your carrier is not in the list, contact your carrier to find out if you can use our pickup endpiont to schedule a pickup with them.

Aramex International
Australia Post MyPost Business
BRT IT
Canada Post
Deutsche Post DHL
Direct Freight
DHL Express
DPD Hungary
DPD Portugal
FedEx
GLS Canada
GLS NL
GLS US
Hermes Germany
Loomis
Redpack
TNT
UPS
USPS
Yamato