Chameleoon API v2

Public and Private REST API for shipment management, courier configuration, webhooks, account management, and payment processing.

Date-Time Format

All date-time values in this API use the format yyyy-MM-ddTHH:mm:ss.fff (e.g., 2025-09-01T08:00:00.000). All timestamps are in the Europe/Bratislava timezone unless explicitly specified otherwise.

Authentication

The API uses two different authentication methods:

Public API Authentication

Public API endpoints use X-Chameleoon-ApiKey header for partner/account-level access. You can view and manage your API key in Chameleoon application on API settings page.

Private API Authentication

Private API endpoints require a Bearer token in the Authorization header.

To obtain a token:

Contact Chameleoon support to receive your M2M client credentials (clientId and clientSecret)
Call POST /v2/auth/m2m with your credentials
Use the returned accessToken in the Authorization: Bearer <token> header

Tokens expire after a period indicated by expiresIn (seconds). Request a new token before expiration.

Security: Do not share your API keys or client credentials in publicly accessible areas such as version control systems or client-side code.

Request ID

Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

Localization

All endpoints support localization via the optional Accept-Language header. Supported languages: sk, cz, en (default: en)

Pagination

List endpoints support pagination with the following query parameters:

page (default: 1, minimum: 1)
pageSize (default: 20, minimum: 1, maximum: 100)

Enumerations

New values can be added to an enumeration without a new API version. Treat a value you do not recognize as unknown instead of failing.

Error Handling

All error responses follow the RFC 9457 Problem Details format.

Type	Status	Description
bad_request	400	Malformed request syntax or invalid parameters
unauthorized	401	Missing or invalid authentication credentials
forbidden	403	Valid credentials but insufficient permissions
not_found	404	Requested resource does not exist
validation_error	422	Business rule or field validation failed
internal_error	500	Unexpected server error

Validation errors (422) include an errors array with per-field details.

Shipping Status

Code	Description
created	Shipping order was created in a courier system.
shipping	A package was picked up by a courier and will be delivered to the addressee.
ready_for_pickup	A courier delivered a package to the selected branch.
ready_for_pickup_2_days	A package is in a branch for more than two days.
not_delivered	A package delivery was unsuccessful.
delivered	A package was delivered successful.
returned	A package was not delivered and will be returned to the sender.
unknown	Shipping status was not handled by Chameleoon API.

Tags

Couriers

Retrieve available courier services and their configuration schemas. Use these endpoints to discover which couriers are available, what countries they deliver to, and what configuration fields each courier requires.

Configurations

Manage courier-specific configurations and profiles that control shipment creation defaults, API credentials, sender addresses, and label printing preferences. Each courier can have multiple profiles representing different delivery methods.

Sources

List the source systems (e-shops, ERPs) activated on the account together with their profiles. A source and one of its profiles form the referenceSource + sourceIdentifier pair a shipment can be attributed to.

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.

Pickups

Schedule courier pickups for prepared shipments. Creates a pickup request with the courier and returns a pickup confirmation document.

Pickup Records

Retrieve created pickup records, view pickup details, and download pickup manifest documents.

Statistics

Reporting over your shipments, as data you can chart or export. Requires the statistics read permission. Each endpoint covers a period set by dateFrom and dateTo, and returns the totals for that period together with the usual breakdowns: by courier, by country, by source and so on. One call gives you every breakdown for the period, so there is nothing to page through and no query to put together. To list the shipments themselves rather than count them, use GET /v2/shipments. A period can cover up to one year and is filtered on the date each shipment was created. Figures are current, not frozen. Every count reflects each shipment's status at generatedAt, not at the end of the period. Re-running a past period returns different numbers until every shipment in it has stopped moving. Breakdowns are independent of one another: there is no way to combine two of them, such as one courier's shipments to one country. For that, list shipments with GET /v2/shipments and aggregate them yourself. For short conversational answers inside an AI assistant rather than a full data set, see the MCP server.

Orders

Orders received from your e-shops and ERP systems, or created manually in Chameleoon. Reading requires the orders read permission; changing orders requires read and write. Each order ships in one or more fulfillments, and each fulfillment becomes one shipment. GET /v2/orders/{id} returns the order with its fulfillments; follow shipmentId to GET /v2/shipments/{id}.

Fulfillments

Parts of your orders that the warehouse picks, packs and ships as one shipment. Requires the fulfillments read permission. Each fulfillment lists its items with picked, packed and skipped quantities. blocked shows that an unresolved incident is blocking it; find it with GET /v2/incidents?orderIds={orderId}&blocking=true. GET /v2/fulfillments/{id} adds the event history. To find the fulfillment of a shipment, use GET /v2/fulfillments?shipmentIds={id}.

Pickings

Picking runs in your warehouse. A picking collects items for one or more fulfillments; the same product from the same location and batch is picked as one line. Requires the pickings read permission. A fulfillment can be part of several pickings, for example when missing items are picked later. List the pickings of an order with GET /v2/pickings?orderIds={orderId}.

Incidents

Problems reported during picking or packing, or manually in Chameleoon, such as a missing or damaged item or a label that could not be created. Requires the incidents read permission. Each incident has a problem type and a severity. A critical incident linked to a fulfillment blocks it until the incident is resolved. List the incidents of an order with GET /v2/incidents?orderIds={orderId}.

Chameleoon Delivery

Activate and manage Chameleoon Delivery — shipping under Chameleoon's own carrier contracts (PPL and Balíkovna) instead of bringing your own courier credentials. Activation is contract-based and mirrors the onboarding wizard in the partner portal:

Create the contract — POST /v2/chameleoon-delivery/contract creates a draft contract (pending, submittedAt unset).
Add at least one pickup address — POST /v2/chameleoon-delivery/contract/addresses.
Add at least one bank account — POST /v2/chameleoon-delivery/contract/bank-accounts (for cash-on-delivery payouts).
Submit for approval — POST /v2/chameleoon-delivery/contract/submit. Chameleoon reviews the contract and moves it to active.
Enable carriers — once the contract is active, enable ppl and/or balikovna via POST /v2/chameleoon-delivery/contract/carriers.

Read the current state, status, addresses, bank accounts, and enabled carriers any time via GET /v2/chameleoon-delivery/contract. Chameleoon Delivery currently operates in Czechia only.

Webhooks

Configure webhook subscriptions to receive real-time HTTP POST notifications. Subscribable events and their payload schemas (the data field of each delivered event):

Shipment lifecycle — shipment_created, shipment_updated, shipment_deleted. Payload: ShipmentResponseDto for created / updated, WebhookDeletedShipmentDto for deleted.
Account lifecycle — account_updated, account_deleted. Payload: WebhookAccountDto for updated, WebhookDeletedAccountDto for deleted.
Configuration lifecycle — configuration_created, configuration_updated, configuration_deleted. Payload: WebhookConfigurationDto, which identifies the affected configuration by courierId and profileId.

Lifecycle events fire on every change regardless of how it was triggered. Webhooks are automatically suspended after repeated delivery failures.