Schedule Pickup

Schedule a pickup for an existing order with an available time slot.

⚠️ Important: Before scheduling a pickup, you must first fetch available pickup times using the pickup availabilities endpoint described below.

Get Pickup Availabilities

Before scheduling any pickup, you must first check what time slots are available for the specific order and date.

Endpoint

GET /orders/{id}/pickup_availabilities

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	ID of an existing order

Request Example

curl -X GET \
  https://stream-orders-api-sandbox.herokuapp.com/client_api/v2/orders/123/pickup_availabilities \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"

Response Example

[
  {
    "pickup_date": "20-01-2024",
    "cut_off_time": "16:00.00",
    "minimum_access_duration_minutes": 180,
    "earliest_pickup_time": "12:00.00",
    "time_zone_id": "America/Chicago"
  },
  {
    "pickup_date": "21-01-2024",
    "cut_off_time": "16:00.00",
    "minimum_access_duration_minutes": 180,
    "earliest_pickup_time": "09:00.00",
    "time_zone_id": "America/Chicago"
  }
]

Response Fields

Field	Type	Description
pickup_date	string	Available pickup date (DD-MM-YYYY format)
cut_off_time	string	Latest time to schedule pickup for this date (HH:MM.SS format)
minimum_access_duration_minutes	integer	Minimum duration required for pickup window (in minutes)
earliest_pickup_time	string	Earliest available pickup time (HH:MM.SS format)
time_zone_id	string	Time zone for all times in this response

Scheduling a Pickup

Description

This will create a scheduled pickup for the specified order and attempt to schedule the pickup with the shipping company. If this fails, an appropriate error message will be returned and the Stream team will be notified of the failure.

Endpoint: POST /orders/{id}/schedule_pickups

Request Parameters

Parameter	Type	Required	Description
id	integer	Yes	ID of an existing order

Request Body

Field	Type	Required	Description
scheduled_pickup.time_from	string	Yes	Start time for pickup window (HH:MM format)
scheduled_pickup.time_to	string	Yes	End time for pickup window (HH:MM format)
scheduled_pickup.scheduled_date	string	Yes	Date for pickup (DD-MM-YYYY format)

Schedule Pickup Request Example

curl -X POST \
  https://stream-orders-api-sandbox.herokuapp.com/client_api/v2/orders/123/schedule_pickups \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_pickup": {
      "time_from": "12:00",
      "time_to": "16:00",
      "scheduled_date": "14-01-2024"
    }
  }'

Success Response (201 Created)

{
  "scheduled_pickup": {
    "id": 14,
    "time_from": "12:00",
    "time_to": "16:00",
    "scheduled_date": "14-01-2024",
    "confirmation_number": "DSD5659S",
    "freight_confirmation_number": "SFEWF65",
    "error_message": null
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": "Invalid input, object invalid"
}

401 Unauthorized

Access token is missing or invalid.

Prerequisites

Before scheduling a pickup, ensure:

1. Order exists - The order must be valid and accessible
2. Available time slot - Check pickup availabilities first to ensure the time slot is available

Response Fields Explained

Field	Description
id	Internal ID of the scheduled pickup
time_from	Start time of the pickup window
time_to	End time of the pickup window
scheduled_date	Date when pickup is scheduled
confirmation_number	Stream's confirmation number for the pickup
freight_confirmation_number	Carrier's confirmation number (if available)
error_message	Any error message from the carrier (null if successful)

Important Notes

• Time Windows: Pickup time windows must fall within the available slots provided by the pickup availabilities endpoint
• Time Zone: All times are in the time zone specified in the pickup availabilities response
• Confirmation Numbers: Both Stream and carrier confirmation numbers may be provided for reference
• Error Handling: If the carrier rejects the pickup request, an error message will be included in the response
• Minimum Duration: The pickup window must meet the minimum access duration requirements
• Cut-off Times: Pickup requests must be made before the cut-off time for same-day or next-day scheduling

Order Status Changes

After successful pickup scheduling:

1. Order status typically changes to "awaiting_pickup"
2. Pickup details become visible in the order information
3. The carrier is notified of the scheduled pickup

Hub Orders

On a hub order both pickup endpoints work on the first leg, the one leaving your origin. Pickup availabilities are that leg's windows and the scheduled pickup is booked against it. There is nothing for you to schedule on the hub → destination leg.

Troubleshooting

If you encounter issues with pickup scheduling:

1. Verify Waybill: Confirm that a waybill has been generated
2. Validate Time Slot: Use the pickup availabilities endpoint to verify the requested time is available
3. Review Error Messages: Any carrier-specific error messages will be included in the response