> For the complete documentation index, see [llms.txt](https://api.documentation.omnicado.com/llms.txt)

# Print a label for a parcel outside Omnicado

> POST /labels/custom
> 
> Prints a label for a parcel that is not an order in Omnicado, with a carrier installed on the account (`customLabels: true` in `/labels/carriers`: Packeta, GLS, PPL, DPD).
> 
> `reference` identifies the parcel. Sending the same reference again returns the label already printed (`200`) and never registers a second parcel with the carrier, so a timed-out request can be safely retried.
> 
> The parcel ships from the expedition address of a selling channel: Packeta uses the channel's Packeta sender label, GLS and PPL its primary expedition address, DPD the DSW set for the channel in the DPD installation. PPL picks the product the expedition would: Smart for a pickup point, Connect outside the Czech Republic, Business otherwise, each in its cash-on-delivery variant when `cashOnDelivery` is sent.



## Servers
- Production API endpoint - live use only: api.services.omnicado.com/api/v2 (Production API endpoint - live use only)
- Development API endpoint - used for testing: api.dev.services.omnicado.com/api/v2 (Development API endpoint - used for testing)


## Authentication methods
- Omnicado token based scheme


## Parameters



### Body: application/json (object)

- **reference** (string)
  Your id of the parcel, unique within the account. Repeating it returns the label already printed instead of a new parcel.

- **carrier** (string)
  A carrier with `customLabels: true` in `/labels/carriers`

- **labelFormat** (string)
  Defaults to the account's label format

- **sender** (object | null)

- **recipient** (object)

- **pickupPointId** (string | null)
  The carrier's pickup point (Packeta point, PPL ParcelShop, DPD Pickup). Without it the parcel is delivered to the address. Not available for GLS.

- **cashOnDelivery** (object)
  Leave out when there is no cash on delivery

- **declaredValue** (object)
  Parcel value. Required for Packeta unless `cashOnDelivery` is sent.

- **parcels** (array[object])
  Packeta carries one parcel per packet; send one request per parcel.

- **note** (string | null)



## Responses
### 201
Label printed

#### Body: application/json (object)
- **orderId** (integer | null)
  Omnicado order id; `null` for a custom label

- **reference** (string)
  Order number, or the `reference` of a custom label

- **carrier** (string)
  Carrier code, or the marketplace delivery (e.g. `alzaDelivery`)

- **labelFormat** (string)
  The format the carrier actually returned

- **trackingNumbers** (array[string])

- **trackingUrl** (string | null)

- **cancelled** (boolean)
  Custom labels only

- **label** (object)


### 200
A label with this reference was printed before; it is returned again

#### Body: application/json (object)
- **orderId** (integer | null)
  Omnicado order id; `null` for a custom label

- **reference** (string)
  Order number, or the `reference` of a custom label

- **carrier** (string)
  Carrier code, or the marketplace delivery (e.g. `alzaDelivery`)

- **labelFormat** (string)
  The format the carrier actually returned

- **trackingNumbers** (array[string])

- **trackingUrl** (string | null)

- **cancelled** (boolean)
  Custom labels only

- **label** (object)


### 400
`validation_failed`

#### Body: application/json (object)
- **error** (string)

- **code** (string)
  Machine-readable reason, listed with each response


### 409
`label_in_progress` (another request with the same reference is still printing); `label_cancelled` (the reference belongs to a cancelled label, use a new one)

#### Body: application/json (object)
- **error** (string)

- **code** (string)
  Machine-readable reason, listed with each response


### 422
`carrier_not_supported`, `carrier_not_installed`, `carrier_not_configured`, `sender_not_found`, `missing_sender_address`, `label_format_not_supported`, `invalid_shipment` (the carrier cannot ship the parcel as sent; `error` says what to change)

#### Body: application/json (object)
- **error** (string)

- **code** (string)
  Machine-readable reason, listed with each response


### 502
`carrier_error`: the carrier refused the parcel; `error` carries its reason

#### Body: application/json (object)
- **error** (string)

- **code** (string)
  Machine-readable reason, listed with each response



[Powered by Bump.sh](https://bump.sh)
