Shipping & tracking

Shipping methods and rates, delivery estimates, shipments and tracking, the branded tracking page and customer shipment emails.

We ship every order from production straight to your customer, under your brand: the tracking page and shipment emails show your brand name, logo and support email (Settings → Branding) — never ours — and parcels ship without our branding.

#Shipping methods

Set shipping_method on the order (default standard). Not every method is available for every destination and product — use the rates endpoint to see what is.

#Get shipping rates

POST /shipping/rates returns the available methods with their price for a destination and a set of items. Use it in your checkout: the price of the method you pick is exactly what the order will charge for shipping. Items are identified like order items; nothing is created.

curl -X POST https://swaglists.com/api/v1/shipping/rates \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": { "country_code": "US", "state_code": "CA", "postal_code": "94107" },
    "items": [{ "sku": "CA-TEE-BLK-M", "quantity": 2 }]
  }'

const res = await fetch("https://swaglists.com/api/v1/shipping/rates", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    recipient: { country_code: "US", state_code: "CA", postal_code: "94107" },
    items: [{ sku: "CA-TEE-BLK-M", quantity: 2 }],
  }),
});
const { data: rates } = await res.json();
for (const r of rates) console.log(r.method, r.price / 100, `${r.estimated_delivery_days.min}-${r.estimated_delivery_days.max} days`);

rates = requests.post(
    "https://swaglists.com/api/v1/shipping/rates",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "recipient": {"country_code": "US", "state_code": "CA", "postal_code": "94107"},
        "items": [{"sku": "CA-TEE-BLK-M", "quantity": 2}],
    },
).json()["data"]
for r in rates:
    print(r["method"], r["price"] / 100, r["estimated_delivery_days"])

{
  "object": "list",
  "data": [
    {
      "object": "shipping_rate",
      "method": "standard",
      "name": "Standard",
      "price": 475,
      "currency": "usd",
      "min_days": 3,
      "max_days": 5,
      "estimated_delivery_days": { "min": 5, "max": 9 }
    }
  ],
  "has_more": false,
  "url": "/api/v1/shipping/rates"
}

• price — shipping price in cents for these items to this destination.
• min_days / max_days — carrier transit time in business days.
• estimated_delivery_days — business days from order to delivery, including production time.

Shipping is priced per parcel group: the first item of a group pays the first-item rate, every additional unit a lower additional-item rate. Ordering several units together is cheaper than separate orders. POST /orders/estimate also returns every method with its price for the full order.

A method that is not available for the destination fails on order creation with 400 shipping_method_unavailable (the message lists the available ones).

#Shipments & tracking

When a parcel leaves production, the order gets a shipment and you receive shipment.created together with order.shipped (or order.partially_shipped when more parcels follow):

{
  "object": "shipment",
  "id": "shp_01k8x9z1m3n5b7v9c1x3z5a7s9",
  "order_id": "ord_01k8x4b2q9w7e3r5t1y8u6i0pa",
  "status": "in_transit",
  "carrier": "usps",
  "service": "USPS Ground Advantage",
  "tracking_number": "9400111899223197428490",
  "tracking_url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223197428490",
  "items": [{ "order_item_id": "oi_01k8x4b2qa3s5d7f9g1h3j5k7l", "quantity": 2 }],
  "shipped_at": "2026-10-23T09:12:44.000Z",
  "estimated_delivery_at": null,
  "delivered_at": null
}

tracking_url always points at the carrier's public tracking page. Push the carrier, number and URL to your store (see the integration guides) or let us email your customer.

shipment.updated fires when the tracking status changes and shipment.delivered when the parcel is delivered; order.delivered follows once every parcel is delivered.

#Branded tracking page

Every confirmed order has a tracking_page_url (https://swaglists.com/track/…): a page with your brand name, logo and colors that shows the order's progress and parcels — no login, no prices, and nothing about us. Link it from your order confirmation email or your customer account pages. Drafts have tracking_page_url: null until you confirm them.

#Customer shipment emails

Turn on Settings → Orders → Email customers when their order ships and we email the recipient (recipient.email) once per parcel when it ships, with the carrier, tracking link and your tracking page — sent under your brand name, with replies going to your support email. Turn it off if your store already sends shipping confirmations. Emails are only sent for live orders.

#Packing slips & branding

Packing slips carry your branding from Settings → Branding (brand name, logo, message, return address) wherever the product ships with a printed slip. Override it per order with packing_slip:

{ "packing_slip": { "brand_name": "Company A Outlet", "message": "Thank you!", "customer_order_number": "#1042", "logo_file_id": "file_01k8x3y1q3w5e7r9t1y3u5i7o9" } }

gift_message is printed for gift orders. Upload logos with POST /files (purpose: logo).