Shipments
Manage shipping orders including creation, listing, retrieval, deletion, and label printing. Supports batch operations for creating up to 100 shipments and deleting up to 100 shipments per request across 40+ supported couriers.
List shipments
Returns a paginated list of shipments for the authenticated account.
Filtering Capabilities:
- Filter by date range using
createdFromandcreatedToparameters - Filter by reference numbers, shipping numbers, or IDs (mutually exclusive)
- Filter by shipment status (multiple values supported)
- Filter by courier and courier profile
query Parameters
pagePage number for pagination
pageSizeNumber of items per page
createdFromFilter shipments created from this date-time (format yyyy-MM-ddTHH:mm:ss.fff)
createdToFilter shipments created until this date-time (format yyyy-MM-ddTHH:mm:ss.fff)
referenceNumbersFilter by reference numbers (max 20 items). Mutually exclusive with shippingNumbers and ids parameters.
idsFilter by shipment IDs (max 20 items). Mutually exclusive with referenceNumbers and shippingNumbers parameters.
shippingNumbersFilter by shipping/tracking numbers (max 20 items). Mutually exclusive with referenceNumbers and ids parameters.
statusFilter by shipment status. Multiple values can be specified.
courierFilter by courier ID (e.g., "gls", "dhl", "dpd")
courierProfileFilter by courier profile (e.g., "na_adresu", "na_pobocku")
Headers
Accept-LanguageLanguage code for localized responses
List shipments › Responses
Paginated list of shipments
pageCurrent page number
pageSizeNumber of items per page
totalPagesTotal number of pages
nextPageWhether a next page exists
previousPageWhether a previous page exists
itemsCountTotal number of items across all pages
List of shipments
Create shipments
Creates one or more shipments. Returns a result containing successfully created shipments and any failures.
Source attribution: every shipment is recorded under a referenceSource +
sourceIdentifier pair, which defaults to api / default. Set both fields to attribute a
shipment to one of your connected sources instead — notification triggers, statistics and
order-state synchronization are keyed on that pair. Shipments in one request may use
different pairs; they are uploaded per courier profile and per source pair.
If duplicate-order prevention is enabled on your API key, that separate check matches on the reference number alone and ignores the source pair — it will reject a reference number already used under a different source.
Headers
Accept-LanguageLanguage code for localized responses
Create shipments › Request Body
courierIdIdentifier of the courier to use for the shipment (e.g., "gls", "dpd", "packeta")
courierProfileDelivery profile for the courier defining the delivery method (e.g., "na_adresu" for home delivery, "na_pobocku" for pickup point)
referenceNumberYour unique reference number for the shipment, typically an order number from your e-commerce system
Recipient address information
Shipment details
Cash on delivery (COD) information
List of packages in the shipment
externalReferenceOptional secondary reference from an external system (e.g., marketplace order ID)
referenceSourceOptional. System the shipment is attributed to. Defaults to api when omitted, empty or blank, so existing integrations that never send this field are unaffected. Notification triggers, statistics attribution and order-state synchronization back to your e-shop or ERP are keyed on the referenceSource + sourceIdentifier pair, so set it when you want a shipment routed as if it originated in one of your connected systems. Use the identifier of a source connected to your account (see GET /v2/sources).
The pair is validated against the sources activated on your account (see GET /v2/sources); a pair that matches none of them is rejected with 422. The values must match the configured source and profile ids exactly, casing included. The pair api / default is always accepted.
referenceSource and sourceIdentifier must be supplied together — send both or neither.
sourceIdentifierOptional. Identifier of the concrete instance of referenceSource, used to distinguish several instances of the same source (for example two e-shops on the same platform). Defaults to default when omitted, empty or blank.
referenceSource and sourceIdentifier must be supplied together — send both or neither.
Courier-specific parameters for this shipment. Keys are matched case insensitively and a key that the selected courier does not support is rejected — with 422 on create, and as a failed item on validate, leaving the rest of the batch validated. A key supplied here overrides the same key configured as a courier profile default. Both key and value must be JSON strings — send "150", not 150.
Supported keys per courier: packeta — courierParcelShopId (the external carrier's own pickup point, required when recipientAddress.parcelShopId is a Packeta carrier rather than a Packeta pickup point); gls — DocumentReturnNumber; sds — EUR, VDP, HAP (numeric) and NRB, NRZ, VDL (true / false); gw — any key, forwarded as a courier text key, except the reserved COD_CASH and COD_CREDIT_CARD (use codPrice instead). Every other courier accepts no parameters.
The shape is the same array of key / value entries that v1 accepts.
Create shipments › Responses
Shipment creation results
Successfully uploaded shipments
Failed shipments
Validate shipments
Validates one or more shipments without creating them. Returns validation results with any errors or warnings.
Headers
Accept-LanguageLanguage code for localized responses
Validate shipments › Request Body
courierIdIdentifier of the courier to use for the shipment (e.g., "gls", "dpd", "packeta")
courierProfileDelivery profile for the courier defining the delivery method (e.g., "na_adresu" for home delivery, "na_pobocku" for pickup point)
referenceNumberYour unique reference number for the shipment, typically an order number from your e-commerce system
Recipient address information
Shipment details
Cash on delivery (COD) information
List of packages in the shipment
externalReferenceOptional secondary reference from an external system (e.g., marketplace order ID)
referenceSourceOptional. System the shipment is attributed to. Defaults to api when omitted, empty or blank, so existing integrations that never send this field are unaffected. Notification triggers, statistics attribution and order-state synchronization back to your e-shop or ERP are keyed on the referenceSource + sourceIdentifier pair, so set it when you want a shipment routed as if it originated in one of your connected systems. Use the identifier of a source connected to your account (see GET /v2/sources).
The pair is validated against the sources activated on your account (see GET /v2/sources); a pair that matches none of them is rejected with 422. The values must match the configured source and profile ids exactly, casing included. The pair api / default is always accepted.
referenceSource and sourceIdentifier must be supplied together — send both or neither.
sourceIdentifierOptional. Identifier of the concrete instance of referenceSource, used to distinguish several instances of the same source (for example two e-shops on the same platform). Defaults to default when omitted, empty or blank.
referenceSource and sourceIdentifier must be supplied together — send both or neither.
Courier-specific parameters for this shipment. Keys are matched case insensitively and a key that the selected courier does not support is rejected — with 422 on create, and as a failed item on validate, leaving the rest of the batch validated. A key supplied here overrides the same key configured as a courier profile default. Both key and value must be JSON strings — send "150", not 150.
Supported keys per courier: packeta — courierParcelShopId (the external carrier's own pickup point, required when recipientAddress.parcelShopId is a Packeta carrier rather than a Packeta pickup point); gls — DocumentReturnNumber; sds — EUR, VDP, HAP (numeric) and NRB, NRZ, VDL (true / false); gw — any key, forwarded as a courier text key, except the reserved COD_CASH and COD_CREDIT_CARD (use codPrice instead). Every other courier accepts no parameters.
The shape is the same array of key / value entries that v1 accepts.
Validate shipments › Responses
Validation results
resultOverall validation result
Individual validation results
Get shipment by ID
Returns details of a specific shipment including tracking information.
path Parameters
idUnique shipment identifier
Headers
Accept-LanguageLanguage code for localized responses
Get shipment by ID › Responses
Shipment details
idUnique shipment identifier
referenceNumberYour reference number for this shipment (typically an order number from your system)
externalReferenceSecondary reference from an external system (e.g., marketplace order ID)
referenceSourceChannel through which the shipment was created (e.g., "api", "web", "shopify")
sourceIdentifierIdentifier of the specific integration or source that created this shipment
courierIdentifier of the courier handling this shipment (e.g., "gls", "dpd", "packeta")
courierProfileDelivery profile used for this shipment (e.g., "na_adresu" for home delivery)
shippingNumbersTracking numbers assigned by the courier, one per package in the shipment
createdTimestamp when the shipment was created in Chameleoon (format yyyy-MM-ddTHH:mm:ss.fff)
Recipient address information
Shipment summary details
Cash on delivery (COD) information
Tracking information for a shipment
List of packages
Delete shipment by ID
Deletes a specific shipment by its unique identifier.
path Parameters
idUnique shipment identifier
Headers
Accept-LanguageLanguage code for localized responses
Delete shipment by ID › Responses
Shipment deleted successfully
Delete multiple shipments
Deletes multiple shipments by their IDs. Maximum 100 shipments per request.
Headers
Accept-LanguageLanguage code for localized responses
Delete multiple shipments › Request Body
idsList of shipment IDs to delete
Delete multiple shipments › Responses
Shipments deleted successfully
Print shipment labels
Generates labels for the specified shipments. Returns a JSON object with the label document as base64 PDF or raw ZPL text, depending on the requested outputType.
Headers
Accept-LanguageLanguage code for localized responses
Print shipment labels › Request Body
shipmentNumbersList of shipping numbers to print labels for
formatLabel paper size format. Passed directly to courier.
outputTypeOutput format type. "pdf" returns base64-encoded PDF, "zpl" returns raw ZPL text.
positionStarting position on A4 label sheet
Print shipment labels › Responses
JSON object with label document
documentBase64-encoded PDF string when outputType is "pdf", or raw ZPL text when outputType is "zpl"
outputTypeThe output format type of the document