# Shipping & tracking

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

Source: https://swaglists.com/docs/shipping

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

| `shipping_method` | Meaning |
| --- | --- |
| `economy` | Cheapest, slowest (not available everywhere). |
| `standard` | Default. Tracked, available for every destination we ship to. |
| `express` | Faster tracked delivery. |
| `priority` | Fastest available service. |

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](https://swaglists.com/docs/orders.md#items); nothing is created.

```bash title="cURL"
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 }]
  }'
```
```js title="Node.js"
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`);
```
```python title="Python"
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"])
```

```json title="Response"
{
  "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`](https://swaglists.com/docs/orders.md#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](https://swaglists.com/docs/objects.md#shipment) and you receive `shipment.created` together with `order.shipped` (or `order.partially_shipped` when more parcels follow):

```json title="order.shipments[0]"
{
  "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](https://swaglists.com/docs/shopify.md)) 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.

| Shipment `status` | Meaning |
| --- | --- |
| `pending` | Created, not yet handed to the carrier. |
| `label_created` | Shipping label created; waiting for carrier pickup. |
| `in_transit` | On its way. |
| `out_for_delivery` | With the carrier for delivery today. |
| `delivered` | Delivered. |
| `exception` | The carrier reported a problem (address, damage, delay). |
| `returned` | Returned to sender. |

## 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`:

```json
{ "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`).