Authentication
Send your secret key as a bearer token in the Authorization header. Keys are scoped to rates, labels or tracking, and a leaked key can be rolled from the dashboard without downtime.
REST API · version 2 · JSON over HTTPS
Ship a label with one request.
The Parcelpath API quotes rates across nine carriers, buys postage, prints labels and pushes tracking events to your server. Every endpoint is described below with its parameters, its errors and the exact request that produced the example response, so you can paste the first call into a terminal and see it work.
The API at a glance
- Uptime over the last twelve months
- 99.98%
- Median response for a rate quote
- 180 ms
- Carriers behind one request shape
- 9
- Endpoints in version 2
- 14
Your first call in three steps
- 01
Create a test key
Request a key below. Keys that start with pk_test_ never buy postage, so you can try every endpoint with real-looking data and no charge.
- 02
Quote a parcel
Send a POST to /v2/rates with an origin, a destination and a parcel weight in grams. The response lists each carrier service with its price and its delivery estimate.
- 03
Buy the label
Pass the rate id from the quote to POST /v2/labels. You receive a PDF or ZPL label URL and a tracking number, and a webhook fires when the first scan arrives.
Things worth knowing before you build
Webhooks
Subscribe to tracking.updated, label.voided and refund.completed. Each delivery is signed with HMAC-SHA256 and retried for 72 hours with growing delays if your server is down.
Idempotent requests
Add an Idempotency-Key header to POST calls and a retry after a timeout returns the original label instead of buying a second one. Keys are remembered for 24 hours.
Endpoint reference
Every endpoint in version 2. Sort by method or by rate limit; the full parameter list for each one opens from its name in the dashboard.
| POST | /v2/rates | Quote services and prices across carriers for one parcel | 600 |
|---|---|---|---|
| POST | /v2/labels | Buy postage and return a label URL with a tracking number | 300 |
| GET | /v2/labels/{id} | Fetch a label, its cost and its current state | 600 |
| DELETE | /v2/labels/{id} | Void an unused label and request a refund | 120 |
| POST | /v2/addresses/verify | Check and standardize a delivery address | 900 |
| GET | /v2/tracking/{number} | Read the full scan history of a shipment | 900 |
| POST | /v2/pickups | Book a carrier collection for a time window | 60 |
| GET | /v2/webhooks | List the endpoints subscribed to your account | 120 |
Official client libraries
Each library is generated from the same OpenAPI file as this reference, so a new field appears in all of them on the same day.
Node.js and TypeScript
npm install parcelpath. Fully typed responses, automatic retries with the idempotency header and a helper that verifies webhook signatures.
Python
pip install parcelpath. Works with sync and async code, returns plain dataclasses and ships a command-line client for quick label checks.
Ruby and PHP
gem install parcelpath, or composer require parcelpath/parcelpath. Both follow the same method names as the REST paths, so the reference reads one-to-one.
Limits and usage plans
Rate quotes are free on every plan. You pay a small fee per label purchased, and limits rise with the plan.
Two months free when billed yearly
Build
For prototypes and test keys.
$0 / month
- 600 rate quotes per minute
- Test mode only
- Community forum support
Ship
For a store that ships every day.
$49 / month
- Live labels at $0.04 each
- Webhooks with 72-hour retries
- Email support within one day
Scale
For marketplaces and fulfilment.
$249 / month
- Labels at $0.02 each
- Dedicated rate-limit pool
- Slack channel with an engineer
Errors and retries
What does a 429 response mean?
You passed the per-minute limit for that endpoint. The Retry-After header tells you how many seconds to wait; the official libraries honor it automatically.
Why did a label request return 409?
An earlier request with the same Idempotency-Key is still being processed. Wait a moment and repeat the call, and you will receive the original result.
How do I move from test to live mode?
Swap the pk_test_ key for a pk_live_ key and add a payment method in the dashboard. Endpoints, parameters and response shapes are identical.
Is there a status page?
Yes. Every incident is posted with a start time and a plain explanation, and you can subscribe by email or webhook.
Request a test key
Tell us what you are building and we will email a test key within a few minutes. No card is needed until you buy a live label.