# 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](/reference/v2-legacy).

## Pickup type at order creation

The `pickup` object inside the [order payload](/reference/v2-legacy) 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}/`](/reference/v2-legacy) directory).

:::note[`POCZTA` and `POINT` are not pickup types]

You may run into `POCZTA` or `POINT` in older integrations or in the Apaczka
panel. Neither is part of the public API contract: `POCZTA` is a leftover of
the retired SOAP API v1, `POINT` only drives the buttons of the panel's order
form. Always send `SELF` and put the point id in `foreign_address_id`.

:::

### `SELF` — own drop-off

```json
"pickup": { "type": "SELF" }
```

After creating the order, download the [waybill](/reference/v2-legacy) and,
for carriers that require it, the [dispatch code](/reference/v2-legacy) to
present at the drop-off location.

### `COURIER` — ordered pickup

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

:::caution[Naming trap]

At order creation the fields are plural — `hours_from` / `hours_to`. The
standalone [`pickup`](/reference/v2-legacy) and
[`batch_pickup`](/reference/v2-legacy) endpoints use the singular
`hour_from` / `hour_to`. Yes, really.

:::

Always check the available windows first with
[`pickup_hours`](/reference/v2-legacy) — the carrier's pickup calendar
depends on the postal code and service:

```json
{ "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).

```json
{ "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:

```json
{
  "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](/sdk) wraps all three endpoints:

```php
$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`](/reference/v2-legacy) 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.