> ## Documentation Index
> Fetch the complete documentation index at: https://api.basetools.cz/llms.txt
> Use this file to discover all available pages before exploring further.

# Shipping labels and tracking numbers

> createPackageManual vs. createPackage + getOrderPackages + getLabel, and how tracking numbers flow back to the order source

A common requirement: get a shipment's tracking number into Base so it can be passed back to the order source (marketplace, e-shop). There are two basic approaches, and in practice they're often combined.

## Approach A — your own carrier integration, just record the number in Base

If you generate the label outside Base (your own GLS/DPD/etc. integration in your WMS), you just write the finished tracking number into Base using [`createPackageManual`](https://api.baselinker.com/index.php?method=createPackageManual).

| Parameter         | Type        | Description                                                                                                                   |
| ----------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `order_id`        | int         | Order ID in Base.                                                                                                             |
| `courier_code`    | varchar(20) | Carrier code from [`getCouriersList`](https://api.baselinker.com/index.php?method=getCouriersList), or a custom carrier name. |
| `package_number`  | varchar(40) | Tracking (consignment) number.                                                                                                |
| `pickup_date`     | int (unix)  | Dispatch date.                                                                                                                |
| `return_shipment` | bool        | Optional, default `false`. Marks the shipment as a return.                                                                    |

```json theme={null}
{
  "order_id": 6910995,
  "courier_code": "dhl",
  "package_number": "622222044730624327700197",
  "pickup_date": 1487006161,
  "return_shipment": false
}
```

`courier_code` still matters here — it's how Base knows which carrier you used and can pass that along to the marketplace correctly.

## Approach B — Base's built-in carrier integration

Most commonly used for marketplace-specific shipping like Allegro ("Wysyłam z Allegro") or Alza Shipping. You need the relevant shipping integration connected and configured in Base first. Then you need three methods:

1. [`createPackage`](https://api.baselinker.com/index.php?method=createPackage) — generates the label with the carrier.
2. [`getOrderPackages`](https://api.baselinker.com/index.php?method=getOrderPackages) — fetches label IDs for an order. Only needed for multi-package shipments; for a single package you already get the ID in the `createPackage` response.
3. [`getLabel`](https://api.baselinker.com/index.php?method=getLabel) — downloads the label itself (base64, PDF/ZPL/EPL/DPL/HTML/GIF depending on the carrier's Base settings).

### createPackage — parameters

| Parameter      | Type        | Description                                                                                                                                                                                                 |
| -------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order_id`     | int         | Order ID.                                                                                                                                                                                                   |
| `courier_code` | varchar(20) | Carrier code. Always `"allegrokurier"` for Allegro shipping.                                                                                                                                                |
| `account_id`   | int         | Optional. Specific shipping account ID ([`getCourierAccounts`](https://api.baselinker.com/index.php?method=getCourierAccounts)); if omitted, the first one found is used.                                   |
| `fields`       | array       | Carrier-specific form fields ([`getCourierFields`](https://api.baselinker.com/index.php?method=getCourierFields) / [`getCourierServices`](https://api.baselinker.com/index.php?method=getCourierServices)). |
| `packages`     | array       | Dimensions (cm) and weight (kg) of the package(s). Add another object to the array for multi-package shipments.                                                                                             |

```json theme={null}
{
  "order_id": 123456789,
  "courier_code": "allegrokurier",
  "account_id": 12123,
  "return_shipment": false,
  "fields": [
    { "id": "courier", "value": "detect" },
    { "id": "insurance", "value": "276.76" },
    { "id": "package_type", "value": "PACKAGE" }
  ],
  "packages": [
    { "length": 20, "height": 10, "width": 30, "weight": 3 }
  ]
}
```

<Warning>
  For cash-on-delivery shipments, also add `{"id": "cod", "value": "123.40"}` to `fields` — note the decimal **dot**, not a comma.
</Warning>

The response includes `package_id`, `package_number` (tracking number), and `courier_inner_number`.

### getOrderPackages and getLabel

```json title="getOrderPackages" theme={null}
{ "order_id": "12345678" }
```

```json title="getLabel" theme={null}
{
  "courier_code": "allegrokurier",
  "package_id": 12345678
}
```

`getLabel` accepts either `package_id` or `package_number` — one is enough. The response includes `extension` (pdf/html/gif/png/epl/zpl/dpl) and `label` as base64.

## How the tracking number gets back to the order source

Depending on the integration's settings in Base, the tracking number is forwarded to the order source either:

* immediately after it's added, or
* when the order is switched to a specific status — note this isn't instant, it runs in batches, typically around 9:00, 10:00, 13:00, 16:00, and 23:00 (± a few minutes). For Alza integrations, the cut-off time (COT) setting also plays a role.

## Deleting a shipment

A created shipment can be deleted with `deleteCourierPackage`. For Alza integrations, a strict rule applies: once a label has been sent to Alza (Shipment Departure occurred), **never delete it** — set the order status to Rejected instead (see [Statuses](/en/objednavky/statusy#cancelled-orders)). Deleting is only safe before the label has been transmitted to the marketplace.

<Tip>
  In practice, both approaches are often combined — your own integration for standard carriers (GLS, DPD, etc.) and Base's integration for marketplace-specific shipping (Alza, Allegro).
</Tip>