Skip to main content
Use this endpoint to retrieve a paginated list of pickups associated with your account or a specific merchant. You can narrow results by status, status category, scheduled date range, or pickup type. The pickupType filter is the quickest way to split your dashboard into Upcoming and Completed views.

​
Authentication

All requests require a valid API key. Company account keys must also include the X-Merchant-Id header.
X-Merchant-Id accepts your businessAccountCode (8-digit), externalMerchantId, or MongoDB _id. Single-business keys do not require this header.

​
Query parameters

​
integer
Page number for pagination. Defaults to 1.
​
integer
Number of results returned per page. Defaults to 30.
​
string
Filter by a specific pickup status string (e.g. new, pendingPickup).
​
string
Filter by status category (e.g. new, completed, cancelled).
​
string
Return pickups scheduled on or after this date. Format: YYYY-MM-DD.
​
string
Return pickups scheduled on or before this date. Format: YYYY-MM-DD.
​
string
Free-text search against pickup number or contact phone number.
​
string
Filter by pickup type. Accepted values: Upcoming or Completed.

​
Example request

​
Response

A successful request returns HTTP 200 with a pickups array and a pagination object.
​
boolean
true on success.
​
array
Array of pickup summary objects. Each item includes pickupId, pickupNumber, pickupDate, picikupStatus, statusCategory, statusLabel, numberOfOrders, pickupFees, phoneNumber, isFragileItems, isLargeItems, pickupNotes, createdAt, and updatedAt.
​
object
Use pickupType=Upcoming to power an active pickups dashboard, and pickupType=Completed for history views. Combine with dateFrom and dateTo to scope results to a specific week or month.