snap
Start free

API

The same endpoints the app uses. JSON in, JSON out, errors as application/problem+json. Create a key under Settings → API & webhooks and send it as Authorization: Bearer sk_….

Rates and labels
POST
/api/v1/rates
Verify an address, create a shipment, return every rate. Body: { to, from?, parcel | parcels[], insurance_cents?, options?, customs?, is_return? }. Send parcels[] for a multi-box shipment: one rate covers every box. Rates expire in 10 minutes.
POST
/api/v1/labels
Buy a rate: { shipment_id, rate_id }. Requires an Idempotency-Key header — a retry with the same key returns the same label, never a second charge.
GET
/api/v1/labels/{id}/file
The label file (PDF, or ZPL if your account is set to ZPL).
POST
/api/v1/labels/{id}/convert
Re-render an existing label: { format: pdf_4x6 | pdf_letter | zpl }.
POST
/api/v1/labels/{id}/void
Request a refund. The card refund follows the carrier's approval.
GET
/api/v1/shipments?status=&q=
Your labels, newest first.
Tracking
GET
/api/v1/tracking/{tracking_number}
Canonical status (label_created · accepted · in_transit · out_for_delivery · delivered · exception · returned) and events for a label you bought.
POST
/api/v1/trackers
Track any package, ours or not: { tracking_number, carrier?, nickname? }.
GET
/api/v1/trackers
Every package you're tracking, with its events.
POST
/api/v1/delivery-estimates
How long each service really takes between two ZIPs: { from_zip, to_zip, planned_ship_date? } → per-service delivery date and days-in-transit at the 50th–99th percentile.
Pickups, manifests, claims
POST
/api/v1/pickups
Ask the carriers to collect a package: { label_id, min_datetime, max_datetime, instructions? } → pickup rates.
POST
/api/v1/pickups/{id}/buy
Confirm one of those rates: { carrier, service }.
POST
/api/v1/pickups/{id}/cancel
Call off a scheduled pickup.
POST
/api/v1/manifests
End-of-day manifest (SCAN form) for a stack of labels from one carrier: { label_ids: [...] }.
GET
/api/v1/manifests
Manifests you've built, with a link to each form.
POST
/api/v1/claims
File an insurance claim on an insured label: { label_id, type: damage | loss | theft, amount_cents, description, contact_email, evidence?: [base64] }.
GET
/api/v1/claims
Your claims and where each one stands.
Reference data
GET
/api/v1/carriers?carriers=usps,ups
Every service code and predefined package you can name in a rate request, with weight limits.
Shipment options

Pass any of these inside options on a rate request. They change the price, so they belong on the rate call, not the buy.

signature
none · signature · adult · indirect
saturday_delivery, hold_for_pickup
Weekend delivery; hold at the carrier's counter
label_date
YYYY-MM-DD, up to a week out
print_custom_1, print_custom_2, invoice_number
Printed on the label
hazmat, dry_ice, alcohol, perishable
Restricted contents — see the carrier's rules
special_rates_eligibility
USPS.MEDIAMAIL · USPS.LIBRARYMAIL
certified_mail, registered_mail, return_receipt
USPS accountable mail
endorsement, machinable, additional_handling, carbon_neutral
Handling and undeliverable-mail instructions
Example — buy a label
curl -X POST https://shipwithsnap.com/api/v1/rates \
  -H "Authorization: Bearer sk_test_…" -H "Content-Type: application/json" \
  -d '{"to":{"name":"Maya Chen","street1":"418 Bergen St","city":"Brooklyn","state":"NY","zip":"11217"},
       "parcel":{"length_in":12,"width_in":9,"height_in":4,"weight_oz":29},
       "insurance_cents":10000,
       "options":{"signature":"adult","print_custom_1":"Order 1042"}}'

curl -X POST https://shipwithsnap.com/api/v1/labels \
  -H "Authorization: Bearer sk_test_…" -H "Idempotency-Key: order-1042" -H "Content-Type: application/json" \
  -d '{"shipment_id":"…","rate_id":"…"}'
Example — international

Anything leaving the US needs a customs object. Every item carries a description, quantity, value, weight and country of origin.

{"to":{"name":"Léa Martin","street1":"12 Rue de Rivoli","city":"Paris","state":"Île-de-France","zip":"75004","country":"FR"},
 "parcel":{"length_in":10,"width_in":8,"height_in":3,"weight_oz":20},
 "customs":{"customs_signer":"Sam Ortiz","contents_type":"merchandise",
   "items":[{"description":"Cotton T-shirt","quantity":2,"value_cents":2400,"weight_oz":8,
             "hs_tariff_number":"6109.10","origin_country":"US"}]}}
Webhooks

Add an https endpoint under Settings → API & webhooks. Events: label.created, label.voided, label.refunded, tracking.updated, tracking.delivered, tracking.exception, batch.completed, batch.partial, pickup.scheduled, pickup.canceled, manifest.created, claim.submitted, claim.updated. Each POST carries x-snap-signature: sha256=HMAC-SHA256(body, secret) and is retried up to 8 times over 24 hours.