Looking for the old docs? View our old docs site.
API Docs

Pickup

The Pickup object allows you to schedule a pickup from your carrier from your customer's residence or place of business. Supported carriers include:

  • Canada Post
  • Canpar
  • DHL Express
  • FedEx
  • Lasership
  • Loomis Express
  • LSO
  • Ontrac
  • UPS
  • USPS
  • Veho

After a Pickup is successfully created, it will automatically fetch PickupRates for each CarrierAccount specified that supports scheduled pickups. Then a PickupRate must be selected and purchased before the pickup can be successfully scheduled.

Endpoints
POST
/pickups
POST
/pickups/:id/buy
POST
/pickups/:id/cancel
GET
/pickups
GET
/pickups/:id

Pickup object

id
string
Unique, begins with "pickup_"
object
string
"Pickup"
reference
string
An optional field that may be used in place of id in some API endpoints
mode
string
"test" or "production"
status
string

Possible values:

  • "scheduled"
  • "canceled"
  • "unknown"
min_datetime
datetime
The earliest time at which the package is available to pick up
max_datetime
datetime
The latest time at which the package is available to pick up. Must be later than min_datetime
is_account_address
boolean
Whether the pickup address is the the account's address
instructions
string
Additional text to help the driver successfully obtain the package
messages
Message array
A list of messages containing carrier errors encountered during pickup rate generation
confirmation
string
The confirmation number for a booked pickup from the carrier
shipment
The associated Shipment
address
The associated Address
carrier_accounts
The list of carriers (if empty, all carriers were used) used to generate pickup rates
pickup_rates
The list of different pickup rates across valid carrier accounts for the shipment
created_at
datetime
When the Pickup was created
updated_at
datetime
When the Pickup was last updated
Pickup Object
{
  "id": "pickup_13e5d7e2a7824432a07975bc553944bc",
  "object": "Pickup",
  "created_at": "2024-01-24T00:06:03Z",
  "updated_at": "2024-01-24T00:06:03Z",
  "mode": "test",
  "status": "unknown",
  "reference": "my-first-pickup",
  "min_datetime": "2024-01-24T00:00:00Z",
  "max_datetime": "2024-01-24T00:00:00Z",
  "is_account_address": false,
  "instructions": "Special pickup instructions",
  "messages": [],
  "confirmation": null,
  "address": {
    "id": "adr_5d1b8e3aba4c11ee98803cecef1b359e",
    "object": "Address",
    "created_at": "2024-01-24T00:06:03+00:00",
    "updated_at": "2024-01-24T00:06:03+00:00",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "8573875756",
    "email": "dr_steve_brule@gmail.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "carrier_accounts": [],
  "pickup_rates": [
    {
      "mode": "test",
      "service": "NextDay",
      "rate": "0.00",
      "currency": "USD",
      "created_at": "2024-01-24T00:06:04Z",
      "updated_at": "2024-01-24T00:06:04Z",
      "carrier": "USPS",
      "pickup_id": "pickup_13e5d7e2a7824432a07975bc553944bc",
      "id": "pickuprate_a6cd2647a898410aa5d33febde44e1b2",
      "object": "PickupRate"
    }
  ]
}

PickupRate object

id
string
Unique, begins with 'pickuprate_'
object
string
"PickupRate"
mode
string
"test" or "production"
service
string
The service name
carrier
string
The name of the carrier
rate
string
The actual rate quote for this service
currency
string
The currency for the rate
pickup_id
string
The ID of the pickup for which this is a quote
created_at
datetime
When the PickupRate was created
updated_at
datetime
When the PickupRate was last updated
PickupRate Object
{
  "mode": "test",
  "service": "NextDay",
  "rate": "0.00",
  "currency": "USD",
  "created_at": "2024-01-24T00:06:04Z",
  "updated_at": "2024-01-24T00:06:04Z",
  "carrier": "USPS",
  "pickup_id": "pickup_13e5d7e2a7824432a07975bc553944bc",
  "id": "pickuprate_a6cd2647a898410aa5d33febde44e1b2",
  "object": "PickupRate"
}

Create a Pickup

Creating a Pickup will automatically fetch rates for the given time frame and location.

Pickups work with an existing purchased Shipment or a fully-purchased Batch, and either a fully-specified Address object or its id. The examples below assume that a Shipment and Address have both already been created.

A Pickup object is immutable once created. All information must be provided during creation; it cannot be modified later.

Request Parameters

address
i.e. Address
shipment
i.e. Shipment (if no batch)
batch
i.e. Batch (if no shipment)
carrier_accounts
i.e. CarrierAccount array
instructions
i.e. "Knock loudly"
reference
i.e. "my-custom-pickup"
is_account_address
i.e. true
min_datetime
i.e. 2014-10-21 10:30:00
max_datetime
i.e. 2014-10-22 10:30:00
POST /pickups
1curl -X POST https://api.easypost.com/v2/pickups \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "pickup": {
6      "reference": "my-first-pickup",
7      "min_datetime": "2022-10-01 10:30:00",
8      "max_datetime": "2022-10-02 10:30:00",
9      "shipment": "shp_...",
10      "address": "adr_...",
11      "is_account_address": "false",
12      "instructions": "Special pickup instructions"
13    }
14  }'
Response
1{
2  "id": "pickup_13e5d7e2a7824432a07975bc553944bc",
3  "object": "Pickup",
4  "created_at": "2024-01-24T00:06:03Z",
5  "updated_at": "2024-01-24T00:06:03Z",
6  "mode": "test",
7  "status": "unknown",
8  "reference": "my-first-pickup",
9  "min_datetime": "2024-01-24T00:00:00Z",
10  "max_datetime": "2024-01-24T00:00:00Z",
11  "is_account_address": false,
12  "instructions": "Special pickup instructions",
13  "messages": [],
14  "confirmation": null,
15  "address": {
16    "id": "adr_5d1b8e3aba4c11ee98803cecef1b359e",
17    "object": "Address",
18    "created_at": "2024-01-24T00:06:03+00:00",
19    "updated_at": "2024-01-24T00:06:03+00:00",
20    "name": "Dr. Steve Brule",
21    "company": null,
22    "street1": "179 N Harbor Dr",
23    "street2": null,
24    "city": "Redondo Beach",
25    "state": "CA",
26    "zip": "90277",
27    "country": "US",
28    "phone": "8573875756",
29    "email": "dr_steve_brule@gmail.com",
30    "mode": "test",
31    "carrier_facility": null,
32    "residential": null,
33    "federal_tax_id": null,
34    "state_tax_id": null,
35    "verifications": {}
36  },
37  "carrier_accounts": [],
38  "pickup_rates": [
39    {
40      "mode": "test",
41      "service": "NextDay",
42      "rate": "0.00",
43      "currency": "USD",
44      "created_at": "2024-01-24T00:06:04Z",
45      "updated_at": "2024-01-24T00:06:04Z",
46      "carrier": "USPS",
47      "pickup_id": "pickup_13e5d7e2a7824432a07975bc553944bc",
48      "id": "pickuprate_a6cd2647a898410aa5d33febde44e1b2",
49      "object": "PickupRate"
50    }
51  ]
52}

Buy a Pickup

To purchase a Pickup, a PickupRate must be specified by its carrier and service name, instead of its id. Our client libraries will handle this automatically if a PickupRate is provided.

Request Parameters

carrier
i.e. "UPS"
service
i.e. "Same-day Pickup"
POST /pickups/:id/buy
1curl -X POST https://api.easypost.com/v2/pickups/pickup_.../buy \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "carrier": "UPS",
6    "service": "Same-Day Pickup"
7  }'
Response
1{
2  "id": "pickup_9eaa3a663af34ffba5ed9a6849edc7fe",
3  "object": "Pickup",
4  "created_at": "2024-01-24T00:06:09Z",
5  "updated_at": "2024-01-24T00:06:31Z",
6  "mode": "test",
7  "status": "scheduled",
8  "reference": "my-first-pickup",
9  "min_datetime": "2024-01-24T00:00:00Z",
10  "max_datetime": "2024-01-24T00:00:00Z",
11  "is_account_address": false,
12  "instructions": "Special pickup instructions",
13  "messages": [],
14  "confirmation": "WTC64065022",
15  "address": {
16    "id": "adr_60557ddaba4c11eea8e7ac1f6bc539aa",
17    "object": "Address",
18    "created_at": "2024-01-24T00:06:09+00:00",
19    "updated_at": "2024-01-24T00:06:09+00:00",
20    "name": "Dr. Steve Brule",
21    "company": null,
22    "street1": "179 N Harbor Dr",
23    "street2": null,
24    "city": "Redondo Beach",
25    "state": "CA",
26    "zip": "90277",
27    "country": "US",
28    "phone": "8573875756",
29    "email": "dr_steve_brule@gmail.com",
30    "mode": "test",
31    "carrier_facility": null,
32    "residential": null,
33    "federal_tax_id": null,
34    "state_tax_id": null,
35    "verifications": {}
36  },
37  "carrier_accounts": [],
38  "pickup_rates": [
39    {
40      "mode": "test",
41      "service": "NextDay",
42      "rate": "0.00",
43      "currency": "USD",
44      "created_at": "2024-01-24T00:06:09Z",
45      "updated_at": "2024-01-24T00:06:09Z",
46      "carrier": "USPS",
47      "pickup_id": "pickup_9eaa3a663af34ffba5ed9a6849edc7fe",
48      "id": "pickuprate_4c3092b06e9342fc848b7ecd28a24f22",
49      "object": "PickupRate"
50    }
51  ]
52}

Cancel a Pickup

You may cancel a Pickup any time before it has been completed. It requires no additional parameters other than the id or reference. The status will change to "canceled" on success.

POST /pickups/:id/cancel
1curl -X POST https://api.easypost.com/v2/pickups/pickup_.../cancel \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "id": "pickup_de371d00d7c1446e9c73ae1f7742c708",
3  "object": "Pickup",
4  "created_at": "2024-01-24T00:06:32Z",
5  "updated_at": "2024-01-24T00:07:15Z",
6  "mode": "test",
7  "status": "canceled",
8  "reference": "my-first-pickup",
9  "min_datetime": "2024-01-24T00:00:00Z",
10  "max_datetime": "2024-01-24T00:00:00Z",
11  "is_account_address": false,
12  "instructions": "Special pickup instructions",
13  "messages": [],
14  "confirmation": "WTC64065024",
15  "address": {
16    "id": "adr_6e5b0cd4ba4c11ee81dcac1f6bc53342",
17    "object": "Address",
18    "created_at": "2024-01-24T00:06:32+00:00",
19    "updated_at": "2024-01-24T00:06:32+00:00",
20    "name": "Dr. Steve Brule",
21    "company": null,
22    "street1": "179 N Harbor Dr",
23    "street2": null,
24    "city": "Redondo Beach",
25    "state": "CA",
26    "zip": "90277",
27    "country": "US",
28    "phone": "8573875756",
29    "email": "dr_steve_brule@gmail.com",
30    "mode": "test",
31    "carrier_facility": null,
32    "residential": null,
33    "federal_tax_id": null,
34    "state_tax_id": null,
35    "verifications": {}
36  },
37  "carrier_accounts": [],
38  "pickup_rates": [
39    {
40      "mode": "test",
41      "service": "NextDay",
42      "rate": "0.00",
43      "currency": "USD",
44      "created_at": "2024-01-24T00:06:33Z",
45      "updated_at": "2024-01-24T00:06:33Z",
46      "carrier": "USPS",
47      "pickup_id": "pickup_de371d00d7c1446e9c73ae1f7742c708",
48      "id": "pickuprate_4c260c126e114a09a4522c7d18b71636",
49      "object": "PickupRate"
50    }
51  ]
52}

Retrieve all Pickups

A list of all Pickup objects associated with the given API Key can also be retrieved. See the Pagination section of our docs for more details on retrieving all records when multiple pages are available.

Request Parameters

before_id
i.e. pickup_...
Optional pagination parameter. Only records created before the given ID will be included. May not be used with after_id.
after_id
i.e. pickup_...
Optional pagination parameter. Only records created after the given ID will be included. May not be used with before_id.
start_datetime
i.e. 2016-01-02T00:00:00Z
Only return records created after this timestamp. Defaults to 1 month ago, or 1 month before a passed end_datetime.
end_datetime
i.e. 2016-01-02T00:00:00Z
Only return records created before this timestamp. Defaults to end of the current day, or 1 month after a passed start_datetime.
page_size
i.e. 20
The number of records to return on each page. The maximum value is 100, and default is 20.
GET /pickups
1curl -X GET https://api.easypost.com/v2/pickups?page_size=5 \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "pickups": [
3    {
4      "id": "pickup_de371d00d7c1446e9c73ae1f7742c708",
5      "object": "Pickup",
6      "created_at": "2024-01-24T00:06:32Z",
7      "updated_at": "2024-01-24T00:07:15Z",
8      "mode": "test",
9      "status": "canceled",
10      "reference": "my-first-pickup",
11      "min_datetime": "2024-01-24T00:00:00Z",
12      "max_datetime": "2024-01-24T00:00:00Z",
13      "is_account_address": false,
14      "instructions": "Special pickup instructions",
15      "messages": [],
16      "confirmation": "WTC64065024",
17      "address": {
18        "id": "adr_6e5b0cd4ba4c11ee81dcac1f6bc53342",
19        "object": "Address",
20        "created_at": "2024-01-24T00:06:32+00:00",
21        "updated_at": "2024-01-24T00:06:32+00:00",
22        "name": "Dr. Steve Brule",
23        "company": null,
24        "street1": "179 N Harbor Dr",
25        "street2": null,
26        "city": "Redondo Beach",
27        "state": "CA",
28        "zip": "90277",
29        "country": "US",
30        "phone": "8573875756",
31        "email": "dr_steve_brule@gmail.com",
32        "mode": "test",
33        "carrier_facility": null,
34        "residential": null,
35        "federal_tax_id": null,
36        "state_tax_id": null,
37        "verifications": {}
38      },
39      "carrier_accounts": [],
40      "pickup_rates": [
41        {
42          "mode": "test",
43          "service": "NextDay",
44          "rate": "0.00",
45          "currency": "USD",
46          "created_at": "2024-01-24T00:06:33Z",
47          "updated_at": "2024-01-24T00:06:33Z",
48          "carrier": "USPS",
49          "pickup_id": "pickup_de371d00d7c1446e9c73ae1f7742c708",
50          "id": "pickuprate_4c260c126e114a09a4522c7d18b71636",
51          "object": "PickupRate"
52        }
53      ]
54    }
55  ],
56  "has_more": true
57}

Retrieve a Pickup

A Pickup object can be retrieved by either an id or reference. However it is recommended to use EasyPost's provided identifiers because uniqueness on reference is not enforced.

GET /pickups/:id
1curl -X GET https://api.easypost.com/v2/pickups/pickup_... \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "id": "pickup_0ccd407d45a24451a8599824d1961989",
3  "object": "Pickup",
4  "created_at": "2024-01-24T00:06:06Z",
5  "updated_at": "2024-01-24T00:06:06Z",
6  "mode": "test",
7  "status": "unknown",
8  "reference": "my-first-pickup",
9  "min_datetime": "2024-01-24T00:00:00Z",
10  "max_datetime": "2024-01-24T00:00:00Z",
11  "is_account_address": false,
12  "instructions": "Special pickup instructions",
13  "messages": [],
14  "confirmation": null,
15  "address": {
16    "id": "adr_5e864f12ba4c11ee8f38ac1f6bc539ae",
17    "object": "Address",
18    "created_at": "2024-01-24T00:06:06+00:00",
19    "updated_at": "2024-01-24T00:06:06+00:00",
20    "name": "Dr. Steve Brule",
21    "company": null,
22    "street1": "179 N Harbor Dr",
23    "street2": null,
24    "city": "Redondo Beach",
25    "state": "CA",
26    "zip": "90277",
27    "country": "US",
28    "phone": "8573875756",
29    "email": "dr_steve_brule@gmail.com",
30    "mode": "test",
31    "carrier_facility": null,
32    "residential": null,
33    "federal_tax_id": null,
34    "state_tax_id": null,
35    "verifications": {}
36  },
37  "carrier_accounts": [],
38  "pickup_rates": [
39    {
40      "mode": "test",
41      "service": "NextDay",
42      "rate": "0.00",
43      "currency": "USD",
44      "created_at": "2024-01-24T00:06:06Z",
45      "updated_at": "2024-01-24T00:06:06Z",
46      "carrier": "USPS",
47      "pickup_id": "pickup_0ccd407d45a24451a8599824d1961989",
48      "id": "pickuprate_c8c474e62dd94c34b2fd8770b848c96e",
49      "object": "PickupRate"
50    }
51  ]
52}