shipzil

OpenRouter for Shipping

One Python interface across Shippo, ShipStation and Easyship.
Bring your own provider accounts. Keep your contracts and negotiated rates.

flowchart LR
    APP["Your application<br/><code>shipzil.Gateway</code>"]

    APP --> SP["Shippo"]
    APP --> SS2["ShipStation v2"]
    APP --> SS1["ShipStation v1"]
    APP --> ES["Easyship"]

    SP --> C["USPS · UPS · FedEx · DHL<br/>and your other carrier accounts"]
    SS2 --> C
    SS1 --> C
    ES --> C

    style APP fill:#4338ca,stroke:#4338ca,color:#fff
    style C fill:#06b6d4,stroke:#06b6d4,color:#fff

One request model in. One rate model out. Each rate remembers which of your accounts produced it, and a purchase goes back through that same account.

Rate and buy

import shipzil as z

gateway = z.Gateway(shipstation_v2="...", shippo="shippo_test_...")

quote = gateway.get_rates(shipment, carriers={"usps"})

rate = quote.cheapest
label = gateway.buy(shipment, rate)

Both providers are queried concurrently. If one fails, the other still returns rates and the failure lands in quote.errors.

import shipzil as z

gateway = z.Gateway(
    shipstation_v2="...",
    shippo="shippo_test_...",
)

shipment = z.Shipment(
    z.Address(
        street1="215 Clayton St",
        city="San Francisco",
        state="CA",
        postal_code="94117",
    ),
    z.Address(
        street1="1600 Pennsylvania Ave NW",
        city="Washington",
        state="DC",
        postal_code="20500",
    ),
    (
        z.Parcel(
            weight=z.Weight.of(16, "oz"),
            dimensions=z.Dimensions.of(10, 8, 4, "in"),
        ),
    ),
)

quote = gateway.get_rates(shipment, carriers={"usps"})

if quote.errors:
    log.warning("some sources failed: %s", quote.errors)

rate = quote.cheapest
if rate is None:
    # No rates, or rates use mixed/unknown currencies.
    raise NoShippingOption(quote.explain())

label = gateway.buy(shipment, rate)

Built for AI agents

Coding agents guess provider semantics badly, so the docs are published in forms an agent can consume directly. make docs-build produces:

Every docs page also has Copy Markdown and Open actions for pasting a single page into a model context.

The invariants an agent most often gets wrong are stated explicitly: a purchase is never retried or redirected, FANOUT rates cannot be bought as one label, and provider service keys are not interchangeable.

Provider support

FANOUT rates are sums of separate per-parcel quotes. They are marked Strategy.FANOUT and cannot be bought as a single label. The Shippo adapter uses FANOUT even though Shippo supports native multi-piece rating for some carrier and account combinations.

Result model

len(quote)          # number of rates
for rate in quote:  # rates in configured-source order
quote.errors        # source-level failures
quote.excluded      # local filtering and provider-reported exclusions
quote.messages      # provider warning messages
quote.cheapest      # lowest amount, only when currency is known and uniform
quote.fastest       # lowest reported delivery_days
quote.explain()     # human-readable diagnostics

Every Rate carries source (your account name), provider, service_key and currency, which may be None on ShipStation v1.

Current boundaries

• No provider health scoring or automatic routing. fallback=(...) is an order you choose.
• Service keys stay provider-scoped. Matching names do not prove equivalent delivery behavior.
• Purchases are never retried or redirected. AmbiguousPurchaseError means the request may have succeeded; reconcile with the provider first.
• cheapest returns None for mixed or unknown currencies. shipzil does not convert money.
• Cross-border rating stops when any item lacks weight or value. EEI data is sent only through the Shippo adapter.

See Concepts and Errors for full behavior.

Install

uv add git+https://github.com/sameerkumar18/shipzil.git

pip install git+https://github.com/sameerkumar18/shipzil.git

Nothing else is pulled in. pip list shows only shipzil.

Pin a commit or tag when you want a fixed version:

uv add git+https://github.com/sameerkumar18/shipzil.git@<commit-or-tag>

Or work from a clone:

git clone https://github.com/sameerkumar18/shipzil.git
cd shipzil
uv sync
uv run python examples/gateway.py

Alpha. The API can still change between commits.

Development

make check           # lint, types and offline tests
make check-compat    # Python 3.10 through 3.14, live tests excluded
make test-live       # loads credentials from .env and calls real providers
make docs-build      # static docs and generated Python reference

Documentation

Quickstart · Concepts · Providers · International · Errors · Reference

License

MIT. Commercial use, modification and distribution are allowed under the terms in LICENSE.

_{"OpenRouter for Shipping" describes the product category. shipzil is not affiliated with OpenRouter.}