# List scheduled pickups

List all pickups that have been scheduled for this carrier

Endpoint: GET /v2/pickups
Version: 2.0.0
Security: api_keys

## Query parameters:

  - `carrier_id` (string)
    Carrier ID
    Example: "se-28529731"

  - `warehouse_id` (string)
    Warehouse ID
    Example: "se-28529731"

  - `created_at_start` (string)
    Only return scheduled pickups that were created on or after a specific date/time
    Example: "2019-03-12T19:24:13.657Z"

  - `created_at_end` (string)
    Only return scheduled pickups that were created on or before a specific date/time
    Example: "2019-03-12T19:24:13.657Z"

  - `page` (integer)
    Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.
    Example: 2

  - `page_size` (integer)
    The number of results to return per response.
    Example: 50

## Response 200 fields (application/json):

  - `pickups` (array, required)
    An array of pickups associated with the user's account.

  - `pickups.pickup_id` (string)
    Pickup Resource ID
    Example: "pik_3YcKU5zdtJuCqoeNwyqqbW"

  - `pickups.label_ids` (array)
    Label IDs that will be included in the pickup request

  - `pickups.created_at` (string)
    The date and time that the pickup was created in ShipStation .
    Example: "2018-09-23T15:00:00.000Z"

  - `pickups.cancelled_at` (string)
    The date and time that the pickup was cancelled in ShipStation .
    Example: "2018-09-23T15:00:00.000Z"

  - `pickups.carrier_id` (string)
    The carrier_id associated with the pickup
    Example: "se-28529731"

  - `pickups.confirmation_number` (string,null)
    The carrier confirmation number for the scheduled pickup.
    Example: "292513CL4A3"

  - `pickups.warehouse_id` (string)
    The warehouse_id associated with the pickup
    Example: "se-28529731"

  - `pickups.pickup_address` (object)
    Any residential or business mailing address, anywhere in the world.

> Note: Either name or company_name must be set. Both may be specified, if relevant.

  - `pickups.pickup_address.name` (string, required)
    The name of a contact person at this address.  This field may be set instead of - or in addition to - the company_name field.
    Example: "John Doe"

  - `pickups.pickup_address.phone` (string, required)
    The phone number of a contact person at this address.  The format of this phone number varies depending on the country.
    Example: "+1 204-253-9411 ext. 123"

  - `pickups.pickup_address.email` (string,null)
    Email for the address owner.
    Example: "example@example.com"

  - `pickups.pickup_address.company_name` (string,null)
    If this is a business address, then the company name should be specified here.
    Example: "The Home Depot"

  - `pickups.pickup_address.address_line1` (string, required)
    The first line of the street address.  For some addresses, this may be the only line.  Other addresses may require 2 or 3 lines.
    Example: "1999 Bishop Grandin Blvd."

  - `pickups.pickup_address.address_line2` (string,null)
    The second line of the street address.  For some addresses, this line may not be needed.
    Example: "Unit 408"

  - `pickups.pickup_address.address_line3` (string,null)
    The third line of the street address.  For some addresses, this line may not be needed.
    Example: "Building #7"

  - `pickups.pickup_address.city_locality` (string, required)
    The name of the city or locality
    Example: "Winnipeg"

  - `pickups.pickup_address.state_province` (string, required)
    The state or province.  For some countries (including the U.S.) only abbreviations are allowed.  Other countries allow the full name or abbreviation.
    Example: "Manitoba"

  - `pickups.pickup_address.postal_code` (string, required)
    postal code
    Example: "78756-3717"

  - `pickups.pickup_address.country_code` (string, required)
    The two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1)
    Example: "CA"

  - `pickups.pickup_address.address_residential_indicator` (string, required)
    Indicates whether this is a residential address.
    Enum: "unknown", "yes", "no"

  - `pickups.contact_details` (object)

  - `pickups.contact_details.name` (string, required)
    Example: "Jonh"

  - `pickups.contact_details.email` (string, required)
    An email address.
    Example: "john.doe@example.com"

  - `pickups.contact_details.phone` (string, required)
    Phone number associated
    Example: "89876752562"

  - `pickups.pickup_notes` (string)
    Used by some carriers to give special instructions for a package pickup
    Example: "call before 15:00"

  - `pickups.pickup_windows` (array)
    An array of available pickup windows. Carriers can return multiple times that they will pickup packages.

  - `pickups.pickup_windows.start_at` (string)
    An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that represents a date and time.
    Example: "2018-09-23T15:00:00.000Z"

  - `pickups.pickup_windows.end_at` (string)
    An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that represents a date and time.
    Example: "2018-09-23T15:00:00.000Z"

  - `total` (integer, required)
    The total number of pickups returned
    Example: 3

  - `page` (integer, required)
    Current page of the list pickups results
    Example: 3

  - `pages` (integer, required)
    Total number of pages for list pickups results
    Example: 4

  - `links` (object, required)
    Helpful links to other pages of results

  - `links.first` (object, required)
    The link to the first page of results.  This object will _always_ have an href field. If there are no results, then the first page will contain an empty array of items.

  - `links.first.href` (string, required)
    The URL of the linked resource, if any
    Example: "http://api.shipstation.com/v2/labels/se-28529731"

  - `links.first.type` (string)
    The type of resource, or the type of relationship to the parent resource
    Example: "child"

  - `links.last` (object, required)
    The link to the final page of results.  This object will _always_ have an href field. If there are no results, then the final page will contain an empty array of items.

  - `links.prev` (object, required)
    The link to the previous page of results.  The href field will only be set when the page is 2 or greater.

  - `links.next` (object, required)
    The link to the next page of results.  The href field will only be set when the page is less than pages.

  - `request_id` (string, required)
    A UUID that uniquely identifies the request id.
This can be given to the support team to help debug non-trivial issues that may occur
    Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"

  - `errors` (array, required)
    The errors associated with the failed API call

  - `errors.error_source` (string, 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 ShipStation API itself.
    Enum: "carrier", "order_source", "ShipStation"

  - `errors.error_type` (string, required)
    The type of error
    Enum: "account_status", "business_rules", "validation", "security", "system", "integrations"

  - `errors.error_code` (string, required)
    The error code specified for the failed API Call
    Enum: "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"

  - `errors.message` (string, required)
    An error message associated with the failed API call
    Example: "Body of request cannot be null."

  - `errors.field_name` (string)
    The name of the field that caused the error (only present for validation errors)
    Example: "inventory_warehouse_id"

  - `errors.field_value` (string)
    The invalid value that was provided for the field (only present for validation errors)
    Example: "invalid-id"

## Response 400 fields (application/json):

  - `request_id` (string, required)
    A UUID that uniquely identifies the request id.
This can be given to the support team to help debug non-trivial issues that may occur
    Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"

  - `errors` (array, required)
    The errors associated with the failed API call

  - `errors.error_source` (string, 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 ShipStation API itself.
    Enum: "carrier", "order_source", "ShipStation"

  - `errors.error_type` (string, required)
    The type of error
    Enum: "account_status", "business_rules", "validation", "security", "system", "integrations"

  - `errors.error_code` (string, required)
    The error code specified for the failed API Call
    Enum: "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"

  - `errors.message` (string, required)
    An error message associated with the failed API call
    Example: "Body of request cannot be null."

  - `errors.field_name` (string)
    The name of the field that caused the error (only present for validation errors)
    Example: "inventory_warehouse_id"

  - `errors.field_value` (string)
    The invalid value that was provided for the field (only present for validation errors)
    Example: "invalid-id"

## Response 404 fields (application/json):

  - `request_id` (string, required)
    A UUID that uniquely identifies the request id.
This can be given to the support team to help debug non-trivial issues that may occur
    Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"

  - `errors` (array, required)
    The errors associated with the failed API call

  - `errors.error_source` (string, 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 ShipStation API itself.
    Enum: "carrier", "order_source", "ShipStation"

  - `errors.error_type` (string, required)
    The type of error
    Enum: "account_status", "business_rules", "validation", "security", "system", "integrations"

  - `errors.error_code` (string, required)
    The error code specified for the failed API Call
    Enum: "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"

  - `errors.message` (string, required)
    An error message associated with the failed API call
    Example: "Body of request cannot be null."

  - `errors.field_name` (string)
    The name of the field that caused the error (only present for validation errors)
    Example: "inventory_warehouse_id"

  - `errors.field_value` (string)
    The invalid value that was provided for the field (only present for validation errors)
    Example: "invalid-id"