Skip to main content
Courier pickup

Methods

Registration of sending parcels from your sender's address

The Courier pickup feature allows sending shipments directly from an address. Through the API, clients can create requests for courier pickup, manage visit time intervals, cancel, and edit requests.

This article outlines the key aspects of working with courier pickup through the API.

Courier pickup API workflow

  1. Creating a courier pickup request

    The client uses the POST /pickups method to create a new courier call request. At this stage, the request is assigned the status Draft. While in this status, the client can:
    • Add or remove shipments.
    • Modify the address or time intervals.
  2. Adding shipments to a courier pickup request

    Shipments are added using the POST /pickups/{id}/shipments method. The client provides an array of shipment IDs to be added.

    Limitations:
    • Shipments must have the status ReadyToShip.
    • Shipments with a different sender's address cannot be added.
  3. Specifying the Date/Time of courier arrival

    After adding shipments, the client must specify the date and time for the courier's visit:
    1. Use POST /time-intervals/find to retrieve available time intervals and select a convenient one.
    2. The selected interval is passed as parameters pickedTimeFrom and pickedTimeTo.
  4. Changing the Request Status

    Once all shipments are added, the client updates the request status to Created using PUT /pickups/{id}/status. In this status, the request awaits processing by the courier.

    Limitations:
    • Shipments must have the status Paid or ContractAfterPayment.
    • Paid or ContractAfterPayment. The request can no longer be modified, except for updating the time interval.
  1. Viewing requests

    The client can retrieve a list of their requests using the GET /pickups method. The response includes the current status of each request.
  2. Cancellation and Deletion
    • To cancel a request in the Created status, the client changes its status to ClientCanceled using the PUT /pickups/{id}/status.
    • To delete a request in the Draft status, the DEL /pickups/{id} method is used.

Courier pickup methods in API

POST /pickups:

Create a courier call request

Response: ID of the created request with the status Draft. While in Draft status, the request can be deleted if the courier call is no longer needed.

Parameters:

  • address: Courier call address (sender's address)
  • pickedTimeFrom and pickedTimeTo: Time interval for courier arrival
  • contactPhone and contactName: Sender's contact details

POST /pickups/{id}/shipments:

Add shipments to a courier call request

Parameters:

  • Array of shipment IDs: shipmentId[]

Conditions:

  • Shipments must have the status ReadyToShip.
  • All shipments in the same request must have the same sender's address.
  • Each shipment can only be added to one courier call request.

PUT /pickups/{id}/status:

Change the status of a request

Response: Confirmation of status change.

  • Changes the request status to Created, confirming readiness for execution. 

    This is possible if the request contains at least one shipment, and all shipments in the request have the status Paid or ContractAfterPayment.
  • Changes the request status from Created to ClientCanceled if it needs to be canceled. 

POST /time-intervals/find:

Retrieve available time intervals for a courier visit

Response: Array of available intervals.

Parameters:

  • address: Courier call address (sender's address)
  • country: Country of dispatch
  • type: Same-day courier call (PickupDayToDay ) or next-day courier call (PickupNextDay)

    Limitations: Same-day courier call (PickupDayToDay) is currently operational in London, Warsaw, Prague, and Berlin. New cities and countries are being added.

    In other cities and countries, next-day courier call (PickupNextDay) is available.

GET /pickups/{id}/shipments:

Retrieve a list of shipments added to a courier call request

Response: List of all shipments added to a specific courier call request.

DEL /pickups/{id}/shipments:

Remove shipments from a request

Parameters:

  • Array of shipment IDs.

Conditions:

  • The request must be in the Draft status. 

DEL /pickups/{id}:

Delete a courier call request

Conditions:

  • Deletes the request entirely if it is in the Draft status.
  • Requests in the Created status cannot be deleted but must be canceled by changing the status to ClientCanceled. 

GET /pickups:

Track the status of current courier call requests

Response: a list of requests with their statuses: Draft, Created, ClientCanceled etc.

Request statuses:

  • Draft: Initial status of the request. In this status, the client can add or remove shipments.
  • Created: The request is ready for processing by the courier.
  • AppointedCourier: A courier has been assigned to the request.
  • InProgress: The courier is en route to the sender's address.
  • ReceivedByCourier: The courier has collected the shipments from the sender and is delivering them to the branch.
  • Done: The courier has completed the request, and the shipments have been delivered to the branch.
  • ClientCanceled: The request was canceled by the client.
  • NotCompleted: The courier canceled the request due to the inability to collect the shipments (e.g., parcels were not ready).
  • Deleted: The request has been removed from the system.

Shipment statuses

Each shipment in a courier call request has an individual status, reflecting its current state during the pickup process (pickup_shipments[...]).

  • Added: The shipment has been added to the request. Available only when the request status is Draft. This is the initial status for each shipment added to the request. 
  • Accepted: The shipment has been successfully accepted by the courier. Applicable only to requests with the status AppointedCourier or InProgress.
  • NotReady: The shipment was removed from the request because it was not ready for dispatch. This status can only be set by the courier and is available for requests with the status AppointedCourier or InProgress.
  • NotPacked: The shipment was not properly packed for handover to the courier. This status can only be set by the courier and is available in requests with the status AppointedCourier or InProgress.
  • ClientCanceled: The shipment was removed from the request at the client's initiative. Available for requests with any status except Draft and Deleted.
  • Deleted: The shipment has been removed from the courier call request. Available only in requests with the status Draft. Deleted shipments can be restored to the Added status. 

Limitations and Key Points

  • Adding and removing shipments is only possible for requests in the Draft status.
  • Requests in the Created status or higher cannot be modified, only canceled, except for updating the time interval.
  • The sender's address for all shipments in a courier call request must be identical, except for the Note field.
  • Time intervals must be selected using the available slots. Same-day time intervals (PickupDayToDay) are not available for all cities. New cities are added progressively.
  • When making changes to a courier call request, the lockVersion field value must be incremented by one.

Detailed API method documentation can be found in the Nova Post API documentation.