---
title: "List Scheduled Pickups"
method: GET
path: "/v1/pickups"
tags: ["package_pickups"]
---

# List Scheduled Pickups

`GET /v1/pickups`

List all pickups that have been scheduled for this carrier

## Query parameters

- `carrier_id` string — A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
- `warehouse_id` string — A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
- `created_at_start` string, date-time
- `created_at_end` string, date-time
- `page` integer
- `page_size` integer

## Response `200`

The request was a success.

- GetPickupsResponseBody — An error response body
  - `pickups` Pickup[], required — An array of pickups associated with the user's account.
    - `pickup_id` string — Pickup Resource ID
    - `label_ids` SeId[] — Label IDs that will be included in the pickup request
    - `created_at` string, date-time — An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that represents a date and time.
    - `cancelled_at` string, date-time — An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that represents a date and time.
    - `carrier_id` string — A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
    - `confirmation_number` string, nullable — The carrier confirmation number for the scheduled pickup.
    - `warehouse_id` string — A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
    - `pickup_address` Address — A complete or partial mailing address.
      - `name` string — The name of a contact person at this address. This field may be set instead of - or in addition to - the `company_name` field.
      - `phone` string — The phone number of a contact person at this address. The format of this phone number varies depending on the country.
      - `email` string, nullable — Email for the address owner.
      - `company_name` string, nullable — If this is a business address, then the company name should be specified here.
      - `address_line1` string — The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
      - `address_line2` string, nullable — The second line of the street address. For some addresses, this line may not be needed.
      - `address_line3` string, nullable — The third line of the street address. For some addresses, this line may not be needed.
      - `city_locality` string — The name of the city or locality
      - `state_province` string — The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
      - `postal_code` string — postal code
      - `country_code` string — A two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1)
      - `address_residential_indicator` 'unknown' | 'yes' | 'no' — Indicates whether an address is residential.
    - `contact_details` ContactDetails
      - `name` string, required
      - `email` string, email, required — An email address.
      - `phone` string, required — Phone number associated
    - `pickup_notes` string — Used by some carriers to give special instructions for a package pickup
    - `pickup_window` PickupWindow — The desired time range for the package pickup.
      - `start_at` string, date-time, required — An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that represents a date and time.
      - `end_at` string, date-time, required — An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that represents a date and time.
    - `pickup_windows` PickupWindows[] — An array of available pickup windows. Carriers can return multiple times that they will pickup packages.
      - `start_at` string, date-time — An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that represents a date and time.
      - `end_at` string, date-time — An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that represents a date and time.
  - `total` integer, required — The total number of pickups returned
  - `page` integer, required — Current page of the list pickups results
  - `pages` integer, required — Total number of pages for list pickups results
  - `links` PaginationLink, required — Helpful links to other pages of results
    - `first` Link, required — A link to a related resource, or an empty object if there is no resource to link to
      - `href` string, url — A URL
      - `type` string — The type of resource, or the type of relationship to the parent resource
    - `last` Link, required — A link to a related resource, or an empty object if there is no resource to link to
      - `href` string, url — A URL
      - `type` string — The type of resource, or the type of relationship to the parent resource
    - `prev` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to
      - `href` string, url — A URL
      - `type` string — The type of resource, or the type of relationship to the parent resource
    - `next` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to
      - `href` string, url — A URL
      - `type` string — The type of resource, or the type of relationship to the parent resource
  - `request_id` string, uuid, required — A UUID (a.k.a. GUID) that uniquely identifies a resource
  - `errors` Error[], required — The errors associated with the failed API call
    - `error_source` 'carrier' | 'order_source' | 'shipengine', required — The source of the error, as indicated by the name this informs us if the API call failed because of the carrier, the order source, or the ShipEngine API itself.
    - `error_type` 'account_status' | 'business_rules' | 'validation' | 'security' | 'system' | 'integrations', required — The type of error
    - `error_code` 'auto_fund_not_supported' | 'batch_cannot_be_modified' | 'carrier_conflict' | 'carrier_disconnected' | 'carrier_not_connected' | 'carrier_not_supported' | 'confirmation_not_supported' | 'default_warehouse_cannot_be_deleted' | 'field_conflict' | 'field_value_required' | 'forbidden' | 'identifier_conflict' | 'identifiers_must_match' | 'insufficient_funds' | 'invalid_address' | 'invalid_billing_plan' | 'invalid_field_value' | 'invalid_identifier' | 'invalid_status' | 'invalid_string_length' | 'label_images_not_supported' | 'meter_failure' | 'order_source_not_active' | 'rate_limit_exceeded' | 'refresh_not_supported' | 'request_body_required' | 'return_label_not_supported' | 'settings_not_supported' | 'subscription_inactive' | 'terms_not_accepted' | 'tracking_not_supported' | 'trial_expired' | 'unauthorized' | 'unknown' | 'unspecified' | 'verification_failure' | 'warehouse_conflict' | 'webhook_event_type_conflict' | 'customs_items_required' | 'incompatible_paired_labels' | 'invalid_charge_event' | 'invalid_object' | 'no_rates_returned' | 'file_not_found' | 'shipping_rule_not_found' | 'service_not_determined' | 'no_rates_returned' | 'funding_source_registration_in_progress' | 'insurance_failure' | 'funding_source_missing_configuration' | 'funding_source_error', required — The error code specified for the failed API Call
    - `message` string, required — An error message associated with the failed API call
    - `carrier_id` string — A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
    - `carrier_code` string — A [shipping carrier](https://www.shipengine.com/docs/carriers/setup/), such as `fedex`, `dhl_express`, `stamps_com`, etc.
    - `field_name` string — The name of the field that caused the error

## Other responses

- `400` — The request contained errors.
- `404` — The specified resource does not exist.
- `500` — An error occurred on ShipEngine's side. > This error will automatically be reported to our engineers.

---

[API](https://skmtc.net/shipengine/apis/shipengine-api.md) · [All operations](https://skmtc.net/shipengine/apis/shipengine-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shipengine/shipengine-api/versions/6af91511d87e/schema)