Shipping Labels and Tracking Numbers in Base.com API

A common requirement when fulfilling orders is getting a shipment’s tracking number into Base so it can be passed back to the order source — whether that’s a marketplace like Allegro or Alza, or your own e-shop. There are two basic approaches, and in practice they’re often combined.

Approach A — Record a tracking number from your own carrier integration

If you generate labels outside Base (for example, through your own GLS, DPD, or similar integration in your WMS), you simply write the finished tracking number into Base using createPackageManual.

Parameter	Type	Description
`order_id`	int	Order ID in Base.
`courier_code`	varchar(20)	Carrier code from `getCouriersList`, or a custom carrier name.
`package_number`	varchar(40)	Tracking (consignment) number.
`pickup_date`	int (unix)	Dispatch date as a Unix timestamp.
`return_shipment`	bool	Optional, default `false`. Marks the shipment as a return.

{
  "order_id": 6910995,
  "courier_code": "dhl",
  "package_number": "622222044730624327700197",
  "pickup_date": 1487006161,
  "return_shipment": false
}

courier_code still matters here — it tells Base which carrier was used so it can pass that information along to the marketplace correctly.

Approach B — Use Base’s built-in carrier integration

Most commonly used for marketplace-specific shipping such as Allegro (“Wysyłam z Allegro”) or Alza Shipping. You need the relevant shipping integration connected and configured in Base first. From there, three methods work in sequence:

createPackage — generates the label with the carrier.
getOrderPackages — fetches label IDs for an order. Only needed for multi-package shipments; for a single package the ID is already returned in the createPackage response.
getLabel — downloads the label itself (base64-encoded, format depends on carrier settings: PDF, ZPL, EPL, DPL, HTML, or GIF).

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 from `getCourierAccounts`; if omitted, the first one found is used.
`fields`	array	Carrier-specific form fields — see `getCourierFields` and `getCourierServices`.
`packages`	array	Dimensions (cm) and weight (kg) of each package. Add another object to the array for multi-package shipments.

{
  "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 }
  ]
}

For cash-on-delivery shipments, add {"id": "cod", "value": "123.40"} to fields. Use a decimal dot, not a comma.

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

getOrderPackages and getLabel

Call getOrderPackages to retrieve label IDs when you have multiple packages on an order:

{ "order_id": "12345678" }

Then call getLabel with either package_id or package_number — one is sufficient:

{
  "courier_code": "allegrokurier",
  "package_id": 12345678
}

The response includes extension (one of pdf, html, gif, png, epl, zpl, dpl) and label as a base64-encoded string.

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 is added, or
When the order is set to a specific status — note this is not 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: once a label has been sent to Alza (Shipment Departure has occurred), never delete it. Set the order status to Rejected instead — see Order Statuses. Deleting a label after transmission will cause reconciliation errors on the Alza side.

In practice, both approaches are often combined — your own integration for standard carriers (GLS, DPD, etc.) and Base’s built-in integration for marketplace-specific shipping (Alza, Allegro).

Get Started

Orders

Products

Returns

Shops API

Base Analytics

Shipping Labels and Tracking Numbers in Base.com API

Approach A — Record a tracking number from your own carrier integration

Approach B — Use Base’s built-in carrier integration

createPackage — parameters

getOrderPackages and getLabel

How the tracking number gets back to the order source

Deleting a shipment

​Approach A — Record a tracking number from your own carrier integration

​Approach B — Use Base’s built-in carrier integration

​createPackage — parameters

​getOrderPackages and getLabel

​How the tracking number gets back to the order source

​Deleting a shipment

Approach A — Record a tracking number from your own carrier integration

Approach B — Use Base’s built-in carrier integration

createPackage — parameters

getOrderPackages and getLabel

How the tracking number gets back to the order source

Deleting a shipment