Shipping Labels

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 Amazon or Walmart, or your own online store. 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 UPS, FedEx, 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. If the courier’s field type for this value is “date” rather than “datetime” (check `getCourierFields` for your courier), Base converts it to an account-local calendar date and discards the time of day. Don’t rely on the time component surviving for those couriers.
`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 Amazon’s Buy Shipping or Ship with Walmart. 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. For example, `"amazonpack"` for Amazon Buy Shipping or `"walmartship"` for Ship with Walmart. See `getCouriersList` for the full set available on your account.
`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.

The packages field contract is metric (centimeters and kilograms). Don’t assume US accounts universally receive or send imperial units here. That said, some individual courier integrations have their own account-level settings that affect how these values are interpreted: for example, USPS has a use_imperial_units option that can change whether raw values are treated as inches/pounds or converted from cm/kg. Use getCourierFields and the courier’s settings in the Base panel as the authoritative source for a specific integration rather than assuming metric end-to-end.

{
  "order_id": 123456789,
  "courier_code": "amazonpack",
  "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 }
  ]
}

If your carrier or marketplace supports cash-on-delivery, 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": "amazonpack",
  "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 that this is not instant: Base runs this on a scheduled backend job rather than in response to your API call, and the exact schedule and timezone aren’t publicly documented. Design for an asynchronous delay of up to a few hours rather than assuming a fixed time of day.

Deleting a shipment

A created shipment can be deleted with deleteCourierPackage. In practice, both approaches are often combined: your own integration for standard carriers (UPS, FedEx, etc.) and Base’s built-in integration for marketplace-specific shipping (Amazon, Walmart).

Get Started

Orders

Products

Returns

Shops API

Base Analytics

Shipping Labels

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