Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Pickups

The API supports two directions: UA and EU. They differ in the processing sequence, the point at which pickup processing begins, and the format of pickup identifiers. Detailed differences in parameters, requests, and responses are described in the documentation for each endpoint.

UA
EU

Processing flow

Create pickup → Courier search → Courier assignment → Pickup processing

Create pickup → Add shipments → Update status → Pickup processing

Processing starts

Immediately after pickup creation

After shipments are added and the pickup status is updated

Pickup ID format

UUID, e.g. 01a0b46a-dfea-7f9c-b1dc-7c7046afbaf7

Integer, e.g. 296132

Retrieve list of courier pickup requests

get
/pickups

This method allows business clients to retrieve a list of all courier pickup requests they have created. Clients can filter the list using specific parameters such as pickup IDs or pickup numbers.

CourierPickupService: This service allows business clients to request a paid courier pickup without pre-creating shipments.

Behavior: A pickup request using the CourierPickupService service can reach the Created status without any associated shipments. Shipments can be added later after the pickup request is created.

Permissions: This service is restricted and available only for authorized business accounts according to individual contract terms. The service is currently available in Moldova.

If the service is not available in your account, please contact your Nova Post account manager or Sales representative.

🔹This method is available to business customers in EU countries where Nova Post operates, as well as in Ukraine. Please note that the shipment parameters for Europe and Ukraine differ.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Query parameters
numbers[]stringOptional

Search pickups by document number. Can accept either a single search number or an array of numbers for conducting the search.

🔹For Ukraine, accepts values in the format 102-0032853. If pickup numbers in both Ukrainian and European formats are provided in the same request, the API returns an error.

Example: PUCZ0000002671
ids[]one ofOptional

A list of pickup request IDs to search. Can accept either a single ID or an array of IDs for conducting the search.

🔹For Ukraine, accepts values in UUID format, for example 01a0b46a-dfea-7f9c-b1dc-7c7046afbaf7. If pickup IDs in both Ukrainian and European formats are provided in the same request, the API returns an error.

🔹The id can be obtained from the Create a courier pickup request response or by searching for the pickup request by its document number.

Example: 28813
integer · int32Optional
or
string · uuidOptional
countryCodes[]string[]Optional

Parameter used to search for pickups in Ukraine.

🔹To retrieve pickups from Ukraine, pass UA in the countryCodes[] array. If the parameter is not provided, only pickups from EU countries are returned.

Example: ["UA"]
serviceCodes[]stringOptional

Filter pickup requests by service code.

Allowed values:

  • CourierPickupService

Returns only pickup requests that contain the specified service.

Example: CourierPickupService
limitinteger · int32Optional

Max number of items to return on page.

Default: 15Example: 1
pageinteger · int32Optional

Number of page to return.

Example: 1
Body
Responses
200

List of courier pickup requests retrieved successfully.

application/json
current_pageinteger · min: 1Optional

The current page of results in the paginated response.

last_pageinteger · min: 1Optional

The last available page in the paginated response.

per_pageinteger · min: 1Optional

The number of items per page.

totalintegerOptional

Total number of pickup requests matching the filter criteria.

get/pickups
GET /v.1.0/pickups HTTP/1.1
Host: api-stage.novapost.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "ids": [
    296132
  ]
}

{
  "current_page": 1,
  "last_page": 1,
  "per_page": 15,
  "total": 1,
  "items": [
    {
      "id": "28813",
      "number": "PUPL0000013342",
      "versionTracking": null,
      "status": "Draft",
      "statusDateTime": "2024-12-20T09:01:56.927000Z",
      "createdAt": "2024-12-20T09:01:56.928000Z",
      "updatedAt": "2024-12-20T11:58:08.731000Z",
      "deletedAt": null,
      "lastPublishedAt": "2024-12-20T11:58:08.000000Z",
      "lastUpdatedAt": "2024-12-20T11:58:08.831311Z",
      "source": "clientapi",
      "executor": null,
      "companyTin": "",
      "companyName": null,
      "fullName": "Chulkov Ihor",
      "phone": "380001234567",
      "email": "i.s.chulkov@gmail.com",
      "country": "Poland",
      "countryCode": "PL",
      "createdByUser": "84dbbfac-3508-11ee-a361-48df37b92096",
      "deliveryPartner": null,
      "lockVersion": 2,
      "divisionId": null,
      "settlementId": 22326,
      "settlementExternalId": null,
      "settlementName": "Warsaw",
      "cityDistrict": null,
      "cityDistrictExternalId": null,
      "address": {
        "postCode": "17890",
        "region": "Warszawa County",
        "city": "Warszawa",
        "street": "15 Sierpnia",
        "building": "1",
        "block": "",
        "flat": "",
        "note": "",
        "address": "17890, Polska, Województwo mazowieckie, Warszawa County, Warszawa, 15 Sierpnia, 1, , , ",
        "addressId": null,
        "latitude": 52.3264159,
        "longitude": 20.9854961,
        "timeZoneId": 367,
        "timeZone": "Europe/Warsaw"
      },
      "addressParts": {
        "postCode": "17890",
        "region": "Warszawa County",
        "city": "Warszawa",
        "street": "15 Sierpnia",
        "building": "1",
        "block": "",
        "flat": "",
        "note": "Information about building entrance for courier access"
      },
      "pickedTimeFrom": "2024-12-01T15:00:00.000000Z",
      "pickedTimeTo": "2024-12-01T18:00:00.000000Z",
      "note": "Test pickup request",
      "currencyCode": "CZK",
      "shipments": [],
      "services": [
        {
          "id": 1040,
          "shipmentParcelRowNumber": "",
          "serviceId": "12292132641000939",
          "pickupId": 604431,
          "serviceType": "PickUpManual",
          "serviceName": "",
          "serviceCode": "CourierPickupService",
          "parcelNumber": "",
          "payerType": "Sender",
          "contractNumber": "string",
          "amount": 150,
          "price": 250,
          "discount": 0,
          "cost": 250,
          "costBeforeCheck": false,
          "paymentStatus": "ContractAfterPayment",
          "currencyCode": "MDL",
          "executionAt": "2026-06-16T10:20:42.564463Z",
          "additionalParameters": {
            "parcel_description": "string",
            "parcels_amount": 10,
            "total_actual_weight": 0,
            "total_volumetric_weight": 0,
            "length": 0,
            "width": 0,
            "height": 0
          }
        }
      ],
      "statuses": [
        {
          "id": 109777,
          "pickupId": 28813,
          "status": "Draft",
          "dateTime": "2024-12-01T13:55:57.350277Z",
          "note": null,
          "user": "d389d1ec-2078-4b62-8bc0-696c72a52a65",
          "createdAt": "2025-01-22T07:58:52.388849Z",
          "updatedAt": "2025-01-22T07:58:52.388849Z",
          "deletedAt": null
        }
      ]
    }
  ]
}

Retrieve available pickup time intervals

post
/time-intervals/find

This method retrieves available time intervals for pickups. The method can also be used to retrieve available time intervals for a specific pickup by providing pickupId.

The algorithm operates based on geographical zones serviced by couriers. These zones are conditional areas on a map defined by logistical features of courier operations. Depending on the pickup location, the system identifies the specific courier responsible for that zone and returns the detailed time intervals available for pickup.

Mandatory Parameters:

  • countryCode: Specifies the country code according to ISO 3166-1 Alpha-2 standard.

  • type: Defines the type of pickup. Allowed values are PickupDayToDay (same-day pickup) or PickupNextDay (next-day pickup).

🔹If pickupId is provided, countryCode and type are optional and do not need to be provided. If pickupId is not provided, countryCode and type are required.

If only countryCode and type are provided, the method will return general courier working hours for the specified country without detailed intervals for a specific location or zone.

Pickup-specific time intervals:

  • pickupId: Specify the identifier of an existing pickup request to retrieve available time intervals for that specific pickup.

  • When pickupId is provided, the response may contain pickupId, actionType, and availableDays with available days and time slots for rescheduling the pickup.

Recommended Parameters for Accurate Results:

  • addressParts: Provide the full pickup address, including building, street, city, region, and postal code. This ensures precise time intervals are returned for the specified address.

  • latitude and longitude: Use geographical coordinates if a full address is not available to determine the zone.

  • divisionId: Specify the ID of the nearest division if the exact address is unknown. However, note that proximity to a division does not guarantee that the courier servicing the address operates from the same division.

Additional Parameters:

  • weight: Time intervals may depend on the shipment's weight. This parameter is helpful for large or weight-sensitive shipments.

Important Notes:

  1. If only countryCode and type are provided, the system will return general working hours of couriers without detailed time intervals for a specific address.

  2. If pickupId is provided, countryCode and type are optional.

  3. For the most accurate time intervals when searching by location, providing a full address or coordinates is strongly recommended.

Time Interval Selection Logic:

  • If a PickupDayToDay configuration exists:

    • It takes priority over PickupNextDay.

    • Today is available if:

      • Not a holiday (holiday == false);

      • A working schedule exists (from != null);

      • Current time < orderTo.

    • Up to 7 calendar days (including today) may be returned if:

      • Not holidays;

      • from is set;

      • orderTo is only checked for today.

  • If no PickupDayToDay, but PickupNextDay is configured:

    • Today is not available.

    • Up to 7 calendar days (excluding today) may be returned if:

      • Not holidays;

      • from is set.

    • orderTo applies only to tomorrow. If current time > orderTo, tomorrow is excluded.

  • If no time interval configuration exists (fallback mode):

    • Today is not available.

    • Up to 7 calendar days (excluding today, weekends, holidays) may be returned.

    • A fixed orderTo = 17:00 applies only to tomorrow.

Note: If from is set but timeIntervals is empty, the courier will arrive sometime during the day without a fixed slot. This logic applies to all types of configurations.

Validation behavior:

  • If the selected day is no longer valid, the system automatically assigns the next available valid day.

  • If the time interval is invalid or empty, the courier will arrive during the full working period.

Recommendation: Providing full address details or coordinates is strongly recommended to ensure accurate time interval results when searching by location.

🔹This method is available to business customers in EU countries where Nova Post operates, as well as in Ukraine. Please note that the shipment parameters for Europe and Ukraine differ.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Body
pickupIdinteger · min: 1Optional

Identifier of the pickup request for which available time intervals must be retrieved.

If pickupId is provided, countryCode and type are optional and do not need to be provided.

typestring · enumOptional

Type of time interval. For EU countries, allowed values are PickupDayToDay or PickupNextDay.

🔹For calls in Ukraine, the supported value is Delivery.

Possible values:
countryCodestringOptional

Country code according to the ISO 3166-1 Alpha-2 standard.

🔹For calls in Ukraine, the parameter value must be UA.

Pattern: ^[A-Z]{2}$
settlementIdinteger · min: 1Optional

Identifier of the settlement where the shipment is to be delivered.

🔹This parameter is required only for calls in Ukraine.

datestringOptional

Pickup date in DD.MM.YYYY format.

🔹This parameter is used only for calls in Ukraine.

Pattern: ^(0[1-9]|[12][0-9]|3[01])\.(0[1-9]|1[0-2])\.[0-9]{4}$
divisionIdinteger · min: 1 · nullableOptional

Division ID for specific branch identification.

latitudenumber · min: -90 · max: 90 · nullableOptional

Latitude for geolocation-based search.

longitudenumber · min: -180 · max: 180 · nullableOptional

Longitude for geolocation-based search.

maxWeightPlaceRecipientinteger · nullableOptional

Weight of the shipment in kilograms. Optional for non-weight-sensitive intervals.

Responses
200

Time intervals retrieved successfully

application/json
idinteger · min: 1Optional

Unique identifier for the time interval.

countryCodestringOptional

Country code according to the ISO 3166-1 Alpha-2 standard.

Pattern: ^[A-Z]{2}$
divisionIdinteger · min: 1 · nullableOptional

Division ID related to the time interval.

typestring · enumOptional

The type of the time interval.

Possible values:
deliveryPartnerstring · nullableOptional

Partner responsible for the pickup, if applicable.

ignoreNonWorkingDaysbooleanOptional

Whether to include non-working days in the search.

createdAtstring · date-timeOptional

The date-time indicating when the record was initially created.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
updatedAtstring · date-timeOptional

The date-time indicating when the record was last updated.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
deletedAtstring · date-time · nullableOptional

The date-time indicating when the record was deleted.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
pickupIdinteger · nullableOptional

Identifier of the pickup request. Returned if pickupId was provided in the request.

actionTypestring · nullableOptional

Type of action for the pickup request.

post/time-intervals/find
POST /v.1.0/time-intervals/find HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 264

{
  "type": "PickupNextDay",
  "countryCode": "CZ",
  "latitude": 50.0755,
  "longitude": 14.4378,
  "maxWeightPlaceRecipient": 5,
  "addressParts": {
    "building": "30",
    "street": "Václavské náměstí",
    "city": "Prague",
    "region": "Central Bohemia",
    "postCode": "11000",
    "note": "Near the statue"
  }
}
{
  "id": 58,
  "countryCode": "HU",
  "divisionId": null,
  "deliveryPartner": null,
  "ignoreNonWorkingDays": false,
  "type": "PickupNextDay",
  "monday": {
    "from": "09:00",
    "to": "18:00",
    "orderTo": "23:59",
    "timeIntervals": []
  },
  "tuesday": {
    "from": "09:00",
    "to": "18:00",
    "orderTo": "23:59",
    "timeIntervals": []
  },
  "wednesday": {
    "from": "09:00",
    "to": "18:00",
    "orderTo": "23:59",
    "timeIntervals": []
  },
  "thursday": {
    "from": "09:00",
    "to": "18:00",
    "orderTo": "23:59",
    "timeIntervals": []
  },
  "friday": {
    "from": "09:00",
    "to": "18:00",
    "orderTo": "23:59",
    "timeIntervals": []
  },
  "saturday": {
    "from": "09:00",
    "to": "18:00",
    "orderTo": "23:59",
    "timeIntervals": []
  },
  "sunday": {
    "from": null,
    "to": null,
    "orderTo": null,
    "timeIntervals": []
  },
  "createdAt": "2025-01-29T09:06:18.365378Z",
  "updatedAt": "2025-11-21T15:49:09.530671Z",
  "deletedAt": null,
  "cityDistricts": null,
  "pickupId": null,
  "actionType": null,
  "availableDays": []
}

Create a courier pickup request

post
/pickups

This method allows business clients to create a new courier pickup request by specifying essential parameters such as the pickup address, parcel type, and additional details.

Initial Status (Draft): The pickup request is created in the Draft status, which allows clients to add all necessary shipments to the request.

Transition to Created: Once all shipments are added, clients must use the Update pickup request status method to change the status to Created. This indicates that the pickup is finalized and ready for processing by the courier service.

🔹Courier pickup requests in Ukraine are created with the ReadyToDone status. This indicates that the pickup request has been completed and is ready for processing by the courier service.

Time Intervals: To include a specific time interval for the pickup, clients should retrieve available time intervals using the corresponding method. This ensures that the requested pickup time aligns with the courier's schedule and availability.

Additional Service – CourierPickupService: Clients can optionally provide information about the planned cargo in the services array using the CourierPickupService service. This allows the client to specify estimated shipment characteristics such as parcel description, quantity, actual and volumetric weight, and optional dimensions. The service is currently available in Moldova. The information is used during pickup planning and courier processing.

🔹This method is available to business customers in EU countries where Nova Post operates, as well as in Ukraine. Please note that the request parameters for Europe and Ukraine differ.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Body
notestring · max: 255Optional

Optional notes or instructions for the courier.

servicesarray · nullableOptional

List of additional services associated with the pickup request.

Currently supported service:

  • CourierPickupService — allows the client to provide planned cargo information that will be used during pickup planning and courier processing.
phonestring · min: 8 · max: 14Required

The contact phone number of the sender, required to allow the courier to reach out if necessary.

emailstring · nullableOptional

While not mandatory, providing an email is recommended as a backup contact method in case the phone number is incorrect or for additional notifications regarding the pickup.

fullNamestring · max: 100Required

Full name of the client sending the parcel, essential for identifying the sender and ensuring accurate handling of the pickup.

companyTinstring · min: 2 · max: 20Optional

The tax identification number (TIN) of a legal entity.

companyNamestring · min: 2 · max: 255Optional

Name of the company requesting the pickup.

countryCodestringRequired

ISO Alpha-2 code for the pickup location.

🔹Different parameters are required depending on whether an EU country or Ukraine (UA) is selected.

Pattern: ^[A-Z]{2}$
settlementIdintegerOptional

Identifier of the settlement where the shipment is to be delivered.

🔹This field is required only for pickups in Ukraine.

isExpressDeliverybooleanOptional

Indicates whether express delivery is required.

  • true — express delivery.
  • false — standard delivery.

🔹This field is used only for pickups in Ukraine.

cargoTypestringOptional

Type of cargo in the shipment.

🔹This field is required only for pickups in Ukraine.

pickedTimeFromstring · date-time · nullableOptional

Start of the pickup time window, selected from available time intervals provided by the method that returns available time slots. If no time slot is specified, the courier will schedule the pickup at their discretion.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
pickedTimeTostring · date-time · nullableOptional

End of the pickup time window, selected from available time intervals provided by the method that returns available time slots. If no time slot is specified, the courier will schedule the pickup at their discretion.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
Responses
201

Pickup request created successfully

application/json
idone ofOptional

Pickup identifier.

  • For Ukraine, a string in UUID format is used, for example 01a0b43d-5649-7a06-bdb1-c9394536dbea.
  • For EU countries, an integer is used, for example 296132.
integer · min: 1Optional
or
string · uuidOptional
numberstringOptional

Pickup number.

  • For Ukraine, the format 102-00328530 is used.
  • For EU countries, the format PUPL7092967496 is used.
Pattern: ^[A-Z]{4}\d{10}$
versionTrackingintegerOptional

Tracking version of the courier pickup request.

🔹This parameter is returned only for pickups in Ukraine.

statusstringOptional

Current pickup status, representing the different stages in the pickup process.

Possible values include:

  • Draft: Initial stage where the pickup request is created but not yet finalized.
  • Created: The pickup request has been created and is ready for processing.
  • AppointedCourier: A courier has been assigned to the pickup request.
  • InProgress: The pickup process is underway.
  • Done: The pickup has been successfully completed.
  • ClientCanceled: The pickup was canceled by the client.
  • NotCompleted: The pickup process could not be completed.
  • Deleted: The pickup request has been removed from the system.
  • ReceivedByCourier: The parcel has been received by the courier.
  • ReadyToDone: The pickup request has been completed and is ready for further processing by the courier service. This value is used only for pickups in Ukraine.
statusDateTimestring · date-timeOptional

Date and time when the status was last updated.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
sourcestring · max: 50Optional

Origin of the request, typically clientapi.

executorstring · max: 50 · nullableOptional

Assigned executor for the pickup, if any.

companyTinstring · min: 2 · max: 20Optional

The tax identification number (TIN) of a legal entity.

companyNamestring · min: 2 · max: 255Optional

Name of the company.

fullNamestring · max: 100Optional

Full name of the requester.

phonestring · min: 8 · max: 14Optional

Contact phone number.

emailstring · nullableOptional

Contact email address, if applicable.

countryCodestringOptional

Country code for the pickup location.

Pattern: ^[A-Z]{2}$
createdByUserstring · max: 50Optional

ID of the user who created the request.

deliveryPartnerstring · nullableOptional

Partner responsible for delivery, if any.

lockVersioninteger · min: 1Optional

Version number for concurrency control.

divisionIdinteger · min: 1 · nullableOptional

Division ID associated with the pickup, if applicable.

settlementIdinteger · min: 1Optional

Settlement ID for the pickup location.

settlementNamestring · nullableOptional

Name of the settlement.

🔹This parameter is returned only for pickups in Ukraine.

cityDistrictstring · max: 50 · nullableOptional

City district of the pickup location, if applicable.

pickedTimeFromstring · date-time · nullableOptional

Start of the pickup time window, specified in request.

pickedTimeTostring · date-time · nullableOptional

End time for the pickup window, specified in request.

notestring · max: 255 · nullableOptional

Note or instructions for the courier.

currencyCodestringOptional

Currency code of the country used for payment transactions.

Pattern: ^[A-Z]{3}$
cargoTypestringOptional

Type of cargo.

🔹This parameter is returned only for pickups in Ukraine.

weightintegerOptional

Total actual weight of the cargo.

🔹This parameter is returned only for pickups in Ukraine.

volumetricWeightintegerOptional

Total volumetric weight of the cargo.

🔹This parameter is returned only for pickups in Ukraine.

parcelsAmountintegerOptional

Number of parcels in the pickup.

🔹This parameter is returned only for pickups in Ukraine.

descriptionstring · nullableOptional

Description of the cargo.

🔹This parameter is returned only for pickups in Ukraine.

payerTypestring · nullableOptional

Type of payer for the services.

🔹This parameter is returned only for pickups in Ukraine.

paymentMethodstringOptional

Payment method.

🔹This parameter is returned only for pickups in Ukraine.

externalIdstring · nullableOptional

Internal data, not for use.

shipmentsobject[]Optional

List of shipments associated with this pickup request.

createdAtstring · date-timeOptional

Date-time of pickup creation.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
updatedAtstring · date-timeOptional

Date-time of the last update.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
deletedAtstring · date-time · nullableOptional

Date-time of delete.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
post/pickups
POST /v.1.0/pickups HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 449

{
  "note": "Test pickup 777",
  "services": [],
  "phone": "48900555111",
  "email": "chucknorris@roundhouse.kick",
  "fullName": "Chuck Norris",
  "companyTin": "",
  "companyName": "",
  "countryCode": "PL",
  "addressParts": {
    "city": "Warszawa",
    "region": "Warszawa County",
    "street": "Admiralska",
    "postCode": "01234",
    "building": "1",
    "flat": "1",
    "block": "",
    "note": "Test shipment, do not process"
  },
  "pickedTimeFrom": "2025-12-11T10:36:25.000000Z",
  "pickedTimeTo": "2025-12-11T10:36:25.000000Z"
}
{
  "id": 296132,
  "number": "PUPL7092967496",
  "status": "Draft",
  "statusDateTime": null,
  "source": "clientapi",
  "executor": null,
  "companyTin": "",
  "companyName": "",
  "fullName": "Chuck Norris",
  "phone": "48900555111",
  "email": "chucknorris@roundhouse.kick",
  "countryCode": "PL",
  "createdByUser": "acab5818-0944-5595-b30c-b788ae280f61",
  "deliveryPartner": null,
  "lockVersion": 1,
  "divisionId": null,
  "settlementId": 22326,
  "cityDistrict": null,
  "address": {
    "string": "01234, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Admiralska, 1, , 1, Test shipment, do not process",
    "latitude": 52.26215209999999,
    "longitude": 21.1792149
  },
  "addressParts": {
    "postCode": "01234",
    "building": "1",
    "street": "Admiralska",
    "city": "Warszawa",
    "region": "Warszawa County",
    "flat": "1",
    "note": "Test shipment, do not process",
    "block": ""
  },
  "pickedTimeFrom": "2025-12-11T10:36:25.000000Z",
  "pickedTimeTo": "2025-12-11T10:36:25.000000Z",
  "note": "Test pickup 777? Тестовий пікап, не обробляйте!",
  "currencyCode": "PLN",
  "externalId": null,
  "shipments": [],
  "services": [],
  "statuses": [
    {
      "id": 634036,
      "pickupId": 296132,
      "status": "Draft",
      "dateTime": "2025-12-11T10:36:28.551560Z",
      "note": null,
      "user": "acab5818-0944-4395-b30c-b788ae280f61",
      "createdAt": "2025-12-11T10:36:28.552814Z",
      "updatedAt": "2025-12-11T10:36:28.552814Z",
      "deletedAt": null
    }
  ],
  "createdAt": "2025-12-11T10:36:28.552814Z",
  "updatedAt": "2025-12-11T10:36:28.552814Z",
  "deletedAt": null
}

Update a courier pickup request

put
/pickups/{id}

The method is used to update the details of an already created pickup request. It allows clients to modify information such as the pickup address, contact details, time window and other parameters in Draft, Created, and AppointedCourier statuses to ensure accurate and timely parcel collection.

When the pickup request is in Created or AppointedCourier status, the pickup time window can be changed only if the pickup date is rescheduled to the next day or later.

🔹This method is available to business customers in EU countries where Nova Post operates, as well as in Ukraine. Please note that the shipment parameters for Europe and Ukraine differ.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Path parameters
idone ofRequired

Pickup identifier. For EU, an integer is used, for example 38556.

🔹For UA, a UUID value is used, for example 01a0b43d-5649-7a06-bdb1-c9394536dbea.

🔹The id can be obtained from the Create a courier pickup request response or by searching for the pickup by its document number in the Retrieve list of courier pickup requests method.

integer · min: 1Optional
or
string · uuidOptional
Body
notestring · max: 255Optional

Optional notes or instructions for the courier.

servicesstring[] · nullableOptional

List of additional services that can be included in the pickup request. This functionality is currently under development.

phonestring · min: 8 · max: 14Required

The contact phone number of the sender, required to allow the courier to reach out if necessary.

emailstring · nullableOptional

While not mandatory, providing an email is recommended as a backup contact method in case the phone number is incorrect or for additional notifications regarding the pickup.

fullNamestring · max: 100Required

Full name of the client sending the parcel, essential for identifying the sender and ensuring accurate handling of the pickup.

companyTinstring · min: 2 · max: 20Optional

The tax identification number (TIN) of a legal entity.

companyNamestring · min: 2 · max: 255Optional

Name of the company requesting the pickup.

lockVersioninteger · min: 1Required

Version number for concurrency control to avoid conflicting updates. When using this method and making updates, the value of this parameter must be incremented by 1 for each subsequent change.

countryCodestringRequired

ISO Alpha-2 code for the pickup location.

Pattern: ^[A-Z]{2}$
preferredDeliveryDatestringOptional

Preferred delivery date in DD.MM.YYYY format.

🔹This parameter is required and used only for courier pickups in Ukraine (UA).

timeIntervalstringOptional

Preferred delivery time interval.

🔹This parameter is used only for courier pickups in Ukraine (UA).

pickedTimeFromstring · date-time · nullableOptional

Start of the pickup time window, selected from available time intervals provided by the method that returns available time slots.

🔹For pickup requests in Created or AppointedCourier status, the time window can be changed only if the pickup date is rescheduled to the next day or later.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
pickedTimeTostring · date-time · nullableOptional

End of the pickup time window, selected from available time intervals provided by the method that returns available time slots.

🔹For pickup requests in Created or AppointedCourier status, the time window can be changed only if the pickup date is rescheduled to the next day or later.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
planedWeightnumberOptional

Planned parcel weight.

🔹This parameter is used only for courier pickups in Ukraine (UA).

Responses
200

Pickup request updated successfully.

application/json
idone ofOptional

Unique identifier for the updated pickup request.

integer · min: 1Optional
or
string · uuidOptional
numberstringOptional

Reference number for the pickup request.

statusstring · enumOptional

Current status of the updated pickup request.

Possible values include:

  • Draft: Initial stage where the pickup request is created but not yet finalized.
  • Created: The pickup request has been created and is ready for processing.
  • AppointedCourier: A courier has been assigned to the pickup request.
Possible values:
lockVersionintegerOptional

Updated version number for concurrency control.

notestring · max: 255Optional

Updated notes for the courier.

pickedTimeFromstring · date-timeOptional

Updated start of the pickup time window.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
pickedTimeTostring · date-timeOptional

Updated end of the pickup time window.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
statusesobject[]Optional

Array of updated status objects tracking pickup status changes.

put/pickups/{id}
PUT /v.1.0/pickups/{id} HTTP/1.1
Host: api-stage.novapost.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 500

{
  "note": "Update note for the pickup",
  "services": [],
  "phone": "420123456789",
  "email": "test@example.cz",
  "fullName": "Updated Test User",
  "companyTin": "CZ98765432",
  "companyName": "Updated Test Company CZ",
  "lockVersion": 2,
  "countryCode": "CZ",
  "addressParts": {
    "city": "Prague",
    "region": "Prague",
    "street": "Národní",
    "postCode": "11000",
    "building": "9",
    "flat": "2",
    "block": "1",
    "note": "Updated building entrance information"
  },
  "pickedTimeFrom": "2024-12-02T14:00:00.000000Z",
  "pickedTimeTo": "2024-12-02T18:00:00.000000Z"
}

{
  "id": 28813,
  "number": "PUCZ0000002671",
  "status": "Draft",
  "lockVersion": 2,
  "note": "Na Rizdvo Sobi",
  "pickedTimeFrom": "2024-12-02T14:00:00.000000Z",
  "pickedTimeTo": "2024-12-02T18:00:00.000000Z",
  "addressParts": {
    "city": "Prague",
    "region": "Prague",
    "street": "Národní",
    "postCode": "11000",
    "building": "9",
    "flat": "2",
    "block": "1",
    "note": "Updated building entrance information"
  },
  "statuses": [
    {
      "id": 109777,
      "status": "Draft",
      "dateTime": "2024-11-13T18:52:57.350277Z",
      "createdAt": "2024-11-13T18:52:57.350861Z",
      "updatedAt": "2024-12-02T14:10:00.000000Z"
    }
  ]
}

Delete a courier pickup request

delete
/pickups/{id}

This method allows business clients to fully delete an existing courier pickup request. When a pickup request is deleted, it is marked as removed in the system, and the deletion date-time is recorded.

🔹This method is available to business customers in EU countries where Nova Post operates, as well as in Ukraine. Please note that the shipment parameters for Europe and Ukraine differ.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Path parameters
idone ofRequired

Pickup identifier. For EU, an integer is used, for example 38556.

🔹For Ukraine, a UUID value is used, for example 01a0b43d-5649-7a06-bdb1-c9394536dbea.

🔹The id can be obtained from the Create a courier pickup request response or by searching for the pickup by its document number in the Retrieve list of courier pickup requests method.

integer · min: 1Optional
or
string · uuidOptional
Responses
200

Pickup request deleted successfully.

application/json
deletedAtstring · date-timeOptional

The date-time when the pickup request was marked as deleted.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$
delete/pickups/{id}
DELETE /v.1.0/pickups/{id} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "deletedAt": "2026-09-18T12:41:43.000000Z"
}

Add shipments to a courier pickup request

post
/pickups/{id}/shipments

This method is used to add already created shipments to an existing courier pickup request. According to the established business process, already created shipments must be added to the courier pickup request after it has been created.

🔹This method is available to business customers in EU countries where Nova Post operates, as well as in Ukraine. Please note that the shipment parameters for Europe and Ukraine differ.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Path parameters
idone ofRequired

Unique identifier of the pickup request to which shipments are being added.

🔹For pickups in Europe (EU), an integer is used.

🔹For pickups in Ukraine (UA), a UUID is used.

🔹The id can be obtained from the Create a courier pickup request response or by searching for the pickup by its document number in the Retrieve list of courier pickup requests method.

integer · min: 1Optional
or
string · uuidOptional
Body
Responses
200

Shipments successfully added to the pickup request.

application/json
failedobject[]Optional

List of shipments that could not be added to the pickup request.

🔹This parameter is returned only for courier deliveries in Ukraine (UA).

post/pickups/{id}/shipments
POST /v.1.0/pickups/{id}/shipments HTTP/1.1
Host: api-stage.novapost.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 61

{
  "shipments": [
    {
      "shipmentId": 1517240
    },
    {
      "shipmentId": 1517330
    }
  ]
}

{
  "shipments": [
    {
      "id": 189608,
      "pickupId": 296132,
      "shipmentId": 1517240,
      "status": "Added",
      "note": null,
      "deliveryPartners": [],
      "processOptions": [],
      "createdAt": "2025-12-11T10:36:28.552814Z",
      "updatedAt": "2025-12-11T10:45:46.929962Z",
      "deletedAt": null
    },
    {
      "id": 189609,
      "pickupId": 296132,
      "shipmentId": 1517330,
      "status": "Added",
      "note": null,
      "deliveryPartners": [],
      "processOptions": [],
      "createdAt": "2025-12-11T10:36:28.552814Z",
      "updatedAt": "2025-12-11T10:45:46.929962Z",
      "deletedAt": null
    }
  ]
}

Remove shipments from a pickup request

delete
/pickups/{id}/shipments

This endpoint allows removing specific shipments from an existing courier pickup request.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Path parameters
idone ofRequired

The unique identifier of the pickup request. For Europe (EU), an integer is used.

🔹For Ukraine (UA), a UUID is used.

🔹The id can be obtained from the Create a courier pickup request response or by searching for the pickup by its document number in the Retrieve list of courier pickup requests method.

integer · min: 1Optional
or
string · uuidOptional
Body
Responses
200

Shipments removed successfully

application/json
delete/pickups/{id}/shipments
DELETE /v.1.0/pickups/{id}/shipments HTTP/1.1
Host: api-stage.novapost.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "shipments": [
    {
      "shipmentId": 370681
    }
  ]
}

{
  "shipments": [
    {
      "deletedAt": "2024-11-13T20:22:56.818679Z"
    }
  ]
}

Update pickup request status

put
/pickups/{id}/status

This method allows updating the status of an existing courier pickup request.

🔹This method is available only for EU countries.

The method can be used to:

  • transition a pickup request from Draft to Created;

  • cancel a pickup request in Created, AppointedCourier, or InProgress status by changing its status to ClientCanceled.

While the request is in Draft status, it remains in a preparatory phase where all necessary shipments can be added. Once the status is updated to Created, the shipment management system recognizes the pickup as finalized and ready for processing by the courier service.

A pickup request can be canceled by the client only using the following status transitions:

  • Created → ClientCanceled;

  • AppointedCourier → ClientCanceled;

  • InProgress → ClientCanceled.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Path parameters
idinteger · min: 1Required

The unique identifier of the pickup request.

🔹The id can be obtained from the Create a courier pickup request response or by searching for the pickup by its document number in the Retrieve list of courier pickup requests method.

Body
statusstring · enumRequired

This field is used to update the status of a courier pickup request.

To finalize a pickup request and make it ready for processing by the shipment management system, change the status from Draft to Created.

To cancel a pickup request, set the status to ClientCanceled. Cancellation is allowed only for pickup requests in Created, AppointedCourier, or InProgress status.

Allowed status transitions:

  • Draft → Created;
  • Created → ClientCanceled;
  • AppointedCourier → ClientCanceled;
  • InProgress → ClientCanceled.

Possible current statuses: Draft, Created, AppointedCourier, InProgress.

Possible values:
lockVersioninteger · min: 1Required

Version number for concurrency control to avoid conflicting updates. When using this method and making updates, the value of this parameter must be incremented by 1 for each subsequent change.

notestring · max: 255Optional

A required note or comment providing additional information about the reason for the status update. This field must be filled when changing the status to ensure proper tracking and context.

Responses
200

Status updated successfully

application/json
successbooleanOptional

Indicates whether the status update was successful.

put/pickups/{id}/status
PUT /v.1.0/pickups/{id}/status HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 77

{
  "status": "Created",
  "lockVersion": 2,
  "note": "Test changhe status to Created!"
}
{
  "success": true
}
PreviousRegisters
NextWebhooks

Last updated