# Schedule a Carrier Pickup With ShipStation API, you can request a carrier pickup at your office, warehouse, or other location using the `/v2/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. Timezones The timezone of the pickup window corresponds to the timezone of the pickup location, not the timezone sent in the request! ## Requirements - Use a carrier that supports scheduling pickups via ShipStation. - 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](https://en.wikipedia.org/wiki/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. ## Sample Request & Response **POST /v2/pickups** ```http POST /v2/pickups HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__ Content-Type: application/json { "label_ids": [ "se-28529731" ], "contact_details": { "name": "John Stuckey", "email": "john.stuckey@example.com", "phone": "6625905259" }, "pickup_notes": "Please knock, doorbell is broken.", "pickup_window": { "start_at": "2024-11-11T15:00:00.000", "end_at": "2024-11-11T18:00:00.000" } } ``` **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). ```json { "pickup_id": "pik_3YcKU5zdtJuCqoeNwyqqbW", "label_ids": [ "se-28529731" ], "created_at": "2024-09-23T15:00:00.000Z", "cancelled_at": "2024-09-23T15:00:00.000Z", "carrier_id": "se-28529731", "warehouse_id": "se-28529731", "confirmation_number": "292513CL4A3", "contact_details": { "name": "string", "email": "john.doe@example.com", "phone": "strings" }, "pickup_notes": "string", "pickup_window": [{ "start_at": "2024-11-11T15:00:00.000Z", "end_at": "2024-11-11T18: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 `/v2/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. ### Sample Request & Response **DELETE /v2/pickups/:pickup_id** ```http DELETE /v2/pickups/pik_3YcKU5zdtJuCqoeNwyqqbW HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__ ``` **Response** If successful, the response includes the ID of the cancelled pickup. ```json { "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 `/v2/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 /v2/pickups** ```http GET /v2/pickups HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__ Content-Type: application/json ``` **Response** ```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": "john.stuckey@example.com", "phone": "6625905259" }, "pickup_notes": "Please knock, doorbell is broken.", "pickup_windows": [ { "start_at": "2024-06-26T11:00:00Z", "end_at": "2024-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": "2024-06-24T13:19:15.75Z", "canceled_at": null } ], "total": 3, "page": 3, "pages": 3, "links": { "first": { "href": "https://api.shipstation.com/v2/pickups?page=1&page_size=1" }, "last": { "href": "https://api.shipstation.com/v2/pickups?page=3&page_size=1" }, "prev": { "href": "https://api.shipstation.com/v2/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 `/v2/pickups/` endpoint. ### Example Request & Response **GET /v2/pickups/:pickup_id** ```http GET /v2/pickups/pik_EzSSBdj2bgrK8tfNAABP9v HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__ Content-Type: application/json ``` **Response** ```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": "john.stuckey@example.com", "phone": "6625905259" }, "pickup_notes": "Please knock, doorbell is broken.", "pickup_windows": [ { "start_at": "2024-06-26T11:00:00Z", "end_at": "2024-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": "2024-06-24T13:19:15.75Z", "canceled_at": null } ```