# Karrio

> Karrio is an open-source, headless multi-carrier shipping platform. One unified REST API
> and a GraphQL management API abstract 30+ carrier integrations behind a single
> resource-oriented interface: live rating, label generation and purchase, package
> tracking, pickups, manifests, orders, customs documents and webhooks. Karrio is
> deployed per instance — self-hosted from Apache-2.0 source, run as the managed Karrio
> Platform, or embedded under a commercial license.

Generated by API Evangelist on 2026-08-27 from the provider's own published surface.
Karrio does not serve an llms.txt of its own (https://karrio.io/llms.txt -> 404,
https://karrio.io/docs/llms.txt -> 404, https://docs.karrio.io/llms.txt -> 404).

## What an agent needs to know first

- THERE IS NO SHARED BASE URL. Karrio runs per instance. The base URL is the URL of the
  Karrio instance you were given. Do not assume a public host.
- api.karrio.io DOES NOT RESOLVE (DNS SERVFAIL on 8.8.8.8 and 1.1.1.1, checked
  2026-08-27) even though it appears as the example host in Karrio's own homepage curl
  sample, webhooks reference and MCP documentation. Any code copied from those pages
  will fail to connect.
- Authentication: send the API token as `Authorization: Token key_xxxxxxxx`, or as the
  HTTP Basic username with an empty password (`-u key_xxxxxxxx:`). A JWT bearer from
  POST /api/token also works. HTTPS is required.
- THERE IS NO IDEMPOTENCY KEY. POST /v1/shipments/{id}/purchase buys a real label and
  incurs a real charge. If a purchase times out, re-read GET /v1/shipments/{id} and
  branch on `status` — do not blind-retry.
- HTTP 424 means the CARRIER rejected the request, not Karrio. The body carries the
  carrier's own message with carrier_name and carrier_id. Do not treat it as a transient
  error and retry unchanged.
- No rate limits are published and no 429 is declared. The throttling signal on this API
  is 424 from a carrier, not 429 from Karrio.
- Test mode is selected by the credential, not by the URL. A test-mode object is
  invisible to a live-mode key, which is the usual cause of an unexpected 404.

## API

- [OpenAPI 3.0.3 — Karrio API 2026.1.32](https://raw.githubusercontent.com/karrioapi/karrio/HEAD/schemas/openapi.yml): 65 paths, 95 operations, 159 schemas. The current contract, first-party, in the monorepo.
- [OpenAPI served on the website](https://karrio.io/openapi.yml): Karrio API 2024.12.6 — 54 paths, 80 operations. STALE by fifteen releases; missing the Products resource. Prefer the repository copy.
- [API reference](https://karrio.io/docs/api-reference): Redoc rendering of the 2024.12.6 spec.
- [GraphQL management API](https://docs.karrio.io/reference/management): POST /graphql on the same instance. 429 types, 69 queries, 112 mutations. Organizations, users, API keys, rate sheets, events, API logs, carrier tracing.

## Resources and operations

- Shipments: create, retrieve, list, update, cancel, purchase a label, fetch new rates, generate documents
- Rating: POST /v1/proxy/rates for a multi-carrier quote without persisting a shipment
- Trackers: add, retrieve, list, update, remove, inject events
- Pickups: schedule, retrieve, list, update, cancel
- Manifests: create, retrieve, list, generate document (NO cancel — manifest creation is one-way)
- Orders: create, retrieve, list, update, cancel
- Addresses, Parcels, Products: full CRUD, reusable across shipments
- Documents: generate, plus HTML template CRUD and upload records
- Batches: import data files, bulk-create orders/shipments/trackers, resend webhooks
- Carriers and Connections: browse the catalog, manage connected carrier accounts
- Webhooks: full CRUD plus a test-fire operation
- Proxy: passthrough to a named carrier for rates, labels, void, pickups, manifest, tracking
- Auth: token issuance, refresh, verify, resource tokens

## Reversibility — what can be taken back

- Label purchase -> POST /v1/shipments/{id}/cancel, until the carrier collects the parcel. Returns 409 once uncancellable.
- Proxy label -> POST /v1/proxy/shipping/{carrier_name}/cancel. Window is carrier-defined.
- Pickup -> POST /v1/pickups/{id}/cancel, before the pickup window opens.
- Order -> POST /v1/orders/{id}/cancel, while unfulfilled. Cancel its labels first.
- Addresses / parcels / products / templates -> DELETE, unconditional.
- NOT REVERSIBLE: manifest creation, document generation, injected tracking events.

## Events

Webhook events are declared by the `enabled_events` enum in the contract, in snake_case:
shipment_purchased, shipment_cancelled, shipment_fulfilled, shipment_out_for_delivery,
shipment_needs_attention, shipment_delivery_failed, tracker_created, tracker_updated,
pickup_scheduled, pickup_cancelled, pickup_closed, order_created, order_updated,
order_fulfilled, order_cancelled, order_delivered, batch_queued, batch_failed,
batch_running, batch_completed, plus the wildcard `all`.

WARNING: https://karrio.io/docs/products/webhooks documents dotted names
("shipment.created", "tracking.status_updated") that are NOT in the enum and will be
rejected. The contract is correct; that page is not.

## MCP

- [Karrio MCP Server](https://karrio.io/docs/developing/mcp-server): first-party, 13 tools plus carrier resources. LOCAL STDIO ONLY — there is no hosted endpoint an agent can call. Documented install is `npx -y @karrio/mcp`, but that package returns 404 on npm as of 2026-08-27 and must be built from packages/mcp in the monorepo.

## SDKs and tooling

- [karrio (PyPI)](https://pypi.org/project/karrio/) — 2026.1.32, 2026-06-23. The maintained SDK.
- [karrio-cli (PyPI)](https://pypi.org/project/karrio-cli/) — 2026.1.32, `kcli`. Carrier-extension development.
- [karrio (npm)](https://www.npmjs.com/package/karrio) — 2023.1.0, last published 2023-01-29. Abandoned.
- @karrio/sdk and @karrio/mcp on npm: both 404. Do not instruct a user to install them.

## Commercial

- [Pricing FAQ](https://karrio.io/platform): self-hosted open source free; managed Scale platform from $499/month pay-as-you-go; commercial embed/white-label license from $50,000/year with unlimited usage. No pricing page, no self-serve checkout (https://karrio.io/pricing -> 404). Bring your own carrier accounts — Karrio does not resell postage.

## Optional

- [Changelog](https://karrio.io/changelog) — per-release rationale, Fix/Feat/Chore, GitHub issue numbers.
- [Self-hosting](https://karrio.io/docs/self-hosting) — Docker, Kubernetes, AWS, GCP, DigitalOcean, OpenTelemetry.
- [Carriers](https://karrio.io/docs/carriers) — the supported carrier catalog.
- [Security policy](https://github.com/karrioapi/karrio/blob/HEAD/SECURITY.md) — report to hello@karrio.io. No security.txt is served on any host.
- [GitHub](https://github.com/karrioapi/karrio) — Apache-2.0 monorepo.
- [Discussions](https://github.com/orgs/karrioapi/discussions) — community support.