Copy page

Integration guides

Pickup types

There are two fundamentally different ways your parcel reaches the carrier, and they are easy to confuse in the API: the pickup type chosen when creating an order (order.pickup.type) and the standalone pickup endpoints for orders that already exist. This page explains both.

Payload examples below follow the API v2 reference.

Pickup type at order creation

The pickup object inside the order payload decides how the parcel is handed over:

Type	Meaning
SELF	You deliver the parcel yourself to the carrier's depot or drop-off location. No courier comes. This is the default.
COURIER	A courier picks the parcel up at the sender address, in the time window you choose.

These are the only two pickup types in the public contract. Dropping the parcel at a parcel point (locker, PUDO, post office) is still SELF — the point itself is selected by foreign_address_id on the sender address (the id comes from the points/{type}/ directory).

SELF — own drop-off

Code
"pickup": { "type": "SELF" }

After creating the order, download the waybill and, for carriers that require it, the dispatch code to present at the drop-off location.

COURIER — ordered pickup

Code
"pickup": {
  "type": "COURIER",
  "date": "2026-07-21",
  "hours_from": "09:00",
  "hours_to": "15:00"
}

Always check the available windows first with pickup_hours — the carrier's pickup calendar depends on the postal code and service:

Code
{ "postal_code": "05-500", "service_id": 65 }

Scheduling a pickup for existing orders

If you created orders with SELF (or the courier did not arrive), you can order a pickup afterwards — without creating a new order:

pickup/{order_id}/ — single order

Re-orders a courier pickup for one existing order. Current constraints:

• available only for DPD orders,
• the account needs the pickup via API privilege (enabled by Apaczka support).

Code
{ "date": "2026-07-21", "hour_from": "09:00", "hour_to": "15:00" }

batch_pickup/ — one courier, many orders

Orders a single pickup for multiple orders at once:

Code
{
  "order_ids": [467840212, 467840211],
  "date": "2026-07-21",
  "hour_from": "09:00",
  "hour_to": "15:00"
}

Constraints checked by the API:

• all orders must have the same sender address,
• all orders must use the same service, and the service must support batch pickup,
• the account needs the pickup via API privilege.

With the SDK

The PHP SDK wraps all three endpoints:

Code
$hours = $client->getPickupHours('05-500', $service)->getHours();
$firstDay = reset($hours);

$client->schedulePickup($orderId, $firstDay->getDate(), '09:00', '15:00');
// or for many orders at once:
$client->scheduleBatchPickup($orderIds, $firstDay->getDate(), '09:00', '15:00');

Which one do I want?

• Shipping ad-hoc, single parcel, courier should come → pickup.type = COURIER directly in order_send.
• Printing labels for many parcels during the day, courier comes once in the afternoon → create orders with SELF, then one batch_pickup for all of them.
• Dropping parcels at a locker/branch on your way → SELF, with the point in the sender's foreign_address_id for point-based services — no pickup needed at all.