Pickups

Schedule carrier pickups at your warehouse or shipping location. Pickups are tied to a carrier account and specify a time window for the carrier driver to collect packages. Currently supported carriers: FedEx.

List Pickups

GET/api/v1/pickups

List all scheduled pickups for the organization.

Requiredpickups:read

Returns a paginated list of pickups ordered by pickup date (newest first).

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 100)
`status`	string	Filter by status: `confirmed`, `completed`, `cancelled`
`carrierAccountId`	string	Filter by carrier account
`fromDate`	string	Filter pickups on or after this date (YYYY-MM-DD)
`toDate`	string	Filter pickups on or before this date (YYYY-MM-DD)


curl -X GET "https://api.orderly-hub.com/api/v1/pickups?status=confirmed&fromDate=2026-01-15" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "organizationId": "uuid",
      "carrierAccountId": "uuid",
      "externalId": "FDXP123456",
      "status": "confirmed",
      "pickupAddress": {
        "address1": "123 Warehouse St",
        "city": "Newark",
        "provinceCode": "NJ",
        "zip": "07102",
        "countryCode": "US"
      },
      "pickupDate": "2026-01-16",
      "readyTime": "09:00",
      "closeTime": "17:00",
      "packageCount": 15,
      "totalWeight": 120,
      "confirmationNumber": "FDXP123456",
      "metadata": {},
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 2, "totalPages": 1, "hasMore": false }
}

Get Pickup

GET/api/v1/pickups/:id

Get a single pickup by ID.

Requiredpickups:read

Returns the full details of a specific pickup including carrier response data and metadata.

Path Parameters

Parameter	Type	Description
`id`	string	Pickup UUID


curl -X GET "https://api.orderly-hub.com/api/v1/pickups/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "uuid",
    "carrierAccountId": "uuid",
    "externalId": "FDXP123456",
    "status": "confirmed",
    "pickupAddress": {
      "address1": "123 Warehouse St",
      "city": "Newark",
      "provinceCode": "NJ",
      "zip": "07102",
      "countryCode": "US"
    },
    "pickupDate": "2026-01-16",
    "readyTime": "09:00",
    "closeTime": "17:00",
    "packageCount": 15,
    "totalWeight": 120,
    "confirmationNumber": "FDXP123456",
    "carrierResponse": { "location": "NWKA" },
    "metadata": {},
    "createdAt": "2026-01-15T10:00:00Z",
    "updatedAt": "2026-01-15T10:00:00Z"
  }
}

Create Pickup

POST/api/v1/pickups

Schedule a new carrier pickup.

Requiredpickups:write

Schedules a pickup with the specified carrier. The carrier account must be active and support pickups. The request is sent to the carrier in real-time and the confirmation number is returned immediately.

Request Body

Field	Type	Required	Description
`carrierAccountId`	string	Yes	Carrier account to use
`pickupAddress`	object	Yes	Pickup address
`pickupDate`	string	Yes	Pickup date (YYYY-MM-DD)
`readyTime`	string	Yes	Earliest pickup time (HH:MM, local time)
`closeTime`	string	Yes	Latest pickup time (HH:MM, local time)
`packageCount`	number	No	Number of packages (default: 1)
`totalWeight`	number	No	Combined weight of all packages
`metadata`	object	No	Custom metadata


curl -X POST "https://api.orderly-hub.com/api/v1/pickups" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "carrierAccountId": "550e8400-e29b-41d4-a716-446655440000",
    "pickupAddress": {
      "address1": "123 Warehouse St",
      "city": "Newark",
      "provinceCode": "NJ",
      "zip": "07102",
      "countryCode": "US"
    },
    "pickupDate": "2026-01-16",
    "readyTime": "09:00",
    "closeTime": "17:00",
    "packageCount": 15,
    "totalWeight": 120
  }'

Response (201)


{
  "pickup": {
    "id": "uuid",
    "organizationId": "uuid",
    "carrierAccountId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "confirmed",
    "pickupDate": "2026-01-16",
    "readyTime": "09:00",
    "closeTime": "17:00",
    "packageCount": 15,
    "confirmationNumber": "FDXP123456",
    "createdAt": "2026-01-15T10:00:00Z"
  },
  "confirmationNumber": "FDXP123456",
  "messages": ["Pickup scheduled successfully"]
}

Cancel Pickup

DELETE/api/v1/pickups/:id

Cancel a scheduled pickup.

Requiredpickups:write

Cancels a scheduled pickup with the carrier. Only pickups in confirmed status can be cancelled. Completed and already-cancelled pickups return a 400 error.

Path Parameters

Parameter	Type	Description
`id`	string	Pickup UUID

Request Body (Optional)

Field	Type	Required	Description
`reason`	string	No	Cancellation reason


curl -X DELETE "https://api.orderly-hub.com/api/v1/pickups/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "No packages ready for pickup"}'

Response


{
  "success": true,
  "messages": ["Cancelled: No packages ready for pickup"]
}

Error Responses

Status	Description
`400`	Pickup is already cancelled or completed
`404`	Pickup not found
`502`	Carrier API error during cancellation