# Schedule a pickup

Schedule a package pickup with a carrier

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

## Request fields (application/json):

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

  - `contact_details` (object, required)

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

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

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

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

  - `pickup_window` (object, required)
    The desired time range for the package pickup.

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

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

## Response 200 fields (application/json):

  - `pickup_id` (string, required)
    Pickup Resource ID
    Example: "pik_3YcKU5zdtJuCqoeNwyqqbW"

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

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

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

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

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

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

  - `pickup_address` (object, required)
    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.

  - `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"

  - `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"

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

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

  - `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."

  - `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"

  - `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"

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

  - `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"

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

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

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

  - `contact_details` (object, required)

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

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

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

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

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

  - `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"

  - `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"

  - `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"