# VeloShip

> VeloShip is a shipping API, an EasyPost alternative: validate addresses, quote rates across FedEx, USPS and UPS, buy labels (PDF, PNG, ZPL), track packages, receive signed webhooks, and apply shipping rules, with separate test and live modes.

- Base URL: https://ship.vprev.dev. The API lives under `/v1` (plus `GET /health`).
- Auth: `Authorization: Bearer <key>`. A key belongs to one organization and one mode. Keep keys on the server; never ship one to a browser.
- Test vs live: `sk_test_...` keys use separate data and mock carriers (free, no real labels). `sk_live_...` keys use real carriers and are billed. Build and test with `sk_test_`. Responses carry `x-api-mode`.
- Units: weights in **ounces** (`parcel.weight`, max 2400), dimensions in **inches**. Money is a **decimal string** like `"12.34"` (USD), never a number. Countries are ISO alpha-2 (default `US`). Timestamps are ISO 8601 UTC.
- Buying: `POST /v1/shipments` with `service` creates and buys in one call. Without `service` it only quotes; then `POST /v1/shipments/{id}/buy` with `rate_id` or `service`.
- Idempotency: send `Idempotency-Key: <uuid>` on every POST that buys. Same key and body replays the first response (`Idempotent-Replayed: true`); keys last 24 hours. Never retry a buy without one.
- Errors: `{ "error": { "code", "message", "details" } }`. Branch on `code`. Retry 429/502/503/504 with the same Idempotency-Key. `502 SHIPMENT.PURCHASE_UNKNOWN` means reconcile, never re-buy.
- Test failures on demand: header `VeloShip-Scenario: <name>` (test keys only).
- Webhooks: `X-Webhook-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">`; verify against the raw body.
- Shipping rules: `order` and `apply_rules` on quotes, shipments and batches; responses report `applied_rules`, `excluded_rates`, `recommended_rate`.
- TypeScript client: `@velopeplabs/ship` (`VeloShipClient`), which adds idempotency, retries and webhook verification.

## Guides

- [Quickstart](https://ship.vprev.dev/docs/md/quickstart.md): Buy a test label in five minutes with curl or the TypeScript client, then go live.
- [API reference](https://ship.vprev.dev/docs/md/api.md): The REST reference: conventions, auth and scopes, test vs live, idempotency, every object and endpoint, webhooks and signatures.
- [Shipping rules](https://ship.vprev.dev/docs/md/rules.md): Conditions, actions, precedence, the `order` object, `apply_rules`, 30 recipes, and how to prompt "Describe a rule in English" (`POST /v1/rules/draft`).
- [Testing with scenarios](https://ship.vprev.dev/docs/md/testing.md): Make the mock carriers fail, slow down or lose a purchase with the `VeloShip-Scenario` header.
- [Convex component](https://ship.vprev.dev/docs/md/convex.md): The Convex component (`@velopeplabs/ship-convex`): quote, buy, batch and track from Convex functions, with reactive mirror tables, a webhook receiver and retry-safe buying.
- [Error codes](https://ship.vprev.dev/docs/md/errors.md): Every error code with its HTTP status and how to handle it (retry, fix the request, reconcile).

## API reference

- [OpenAPI 3.1 spec](https://ship.vprev.dev/openapi.json): the machine-readable API, generated from the validation schemas the routes use.
- [Interactive API docs](https://ship.vprev.dev/docs/): Scalar UI for browsing and trying endpoints.

## Agent skill

An Agent Skill for integrators (Claude Code, Cursor and other assistants that read SKILL.md). Install it into a project:

```sh
mkdir -p .claude/skills/veloship && cd .claude/skills/veloship
curl -s https://ship.vprev.dev/skills/veloship/files.txt | while read f; do curl -s --create-dirs -o "$f" "https://ship.vprev.dev/skills/veloship/$f"; done
```

- [SKILL.md](https://ship.vprev.dev/skills/veloship/SKILL.md): The integration workflow, the rules that prevent the common mistakes, and when to load each reference.
- [references/api.md](https://ship.vprev.dev/skills/veloship/references/api.md): Compact endpoint and object cheat sheet.
- [references/errors.md](https://ship.vprev.dev/skills/veloship/references/errors.md): Error handling by class, with retry and reconcile logic.
- [references/recipes.md](https://ship.vprev.dev/skills/veloship/references/recipes.md): Working code: Node/TypeScript (client and fetch), Python, order-to-label flow, 4x6 printing.
- [references/rules.md](https://ship.vprev.dev/skills/veloship/references/rules.md): Shipping rules: JSON shape, fields, operators, actions, `apply_rules`, drafting in English.
- [references/webhooks.md](https://ship.vprev.dev/skills/veloship/references/webhooks.md): Events, retries, signature verification in Node, Python and Workers.

## Optional

- [Full documentation in one file](https://ship.vprev.dev/llms-full.txt): all guides above plus a compact endpoint reference (large; prefer the individual guides).
- [Skill file list](https://ship.vprev.dev/skills/veloship/files.txt): one path per line, for downloading the skill.