Shipments

List shipments, view details, and void/refund labels.

List Shipments

GET /api/v1/shipments

Returns a paginated list of shipments for your account.

Query Parameters

Example

curl "https://shipwave.app/api/v1/shipments?carrier=usps&limit=25" \
  -H "Authorization: Bearer sw_live_abc123..."

const res = await fetch(
  "https://shipwave.app/api/v1/shipments?carrier=usps&limit=25",
  { headers: { Authorization: "Bearer sw_live_abc123..." } }
);
const { data, meta } = await res.json();

Response

{
  "data": [
    {
      "id": "clx2ship1",
      "easypostId": "shp_abc123",
      "trackingCode": "9400111899223100012345",
      "status": "purchased",
      "carrierCode": "usps",
      "labelUrl": "https://easypost-files.s3.amazonaws.com/label.png",
      "createdAt": "2026-02-18T16:00:00.000Z",
      "voidedAt": null,
      "selectedRate": {
        "carrier": "USPS",
        "service": "Priority Mail",
        "rate": "12.50"
      },
      "toAddress": {
        "name": "Jane Smith",
        "street1": "123 Main St",
        "city": "Austin",
        "state": "TX",
        "zip": "78701",
        "country": "US"
      },
      "fromAddress": {
        "name": "Main Warehouse",
        "street1": "500 Commerce Dr",
        "city": "Portland",
        "state": "OR",
        "zip": "97201",
        "country": "US"
      },
      "parcel": {
        "weight": 32.5,
        "length": 12.0,
        "width": 8.0,
        "height": 6.0
      },
      "orderShipments": [
        {
          "orderId": "clx1abc2d3efg",
          "order": {
            "orderNumber": "1042",
            "customerName": "Jane Smith"
          }
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "limit": 25,
    "total": 142,
    "totalPages": 6
  }
}

---

Get Shipment

GET /api/v1/shipments/:id

Returns full details for a single shipment including rates, addresses, and linked orders.

Example

curl https://shipwave.app/api/v1/shipments/clx2ship1 \
  -H "Authorization: Bearer sw_live_abc123..."

Errors

---

Void / Refund Label

POST /api/v1/shipments/:id/void

Voids a shipping label and requests a refund from the carrier. The linked order's status is reset to pending.

Prerequisites

• The shipment must not already be voided
• The shipment must have an EasyPost ID

Example

curl -X POST https://shipwave.app/api/v1/shipments/clx2ship1/void \
  -H "Authorization: Bearer sw_live_abc123..."

const res = await fetch(
  "https://shipwave.app/api/v1/shipments/clx2ship1/void",
  {
    method: "POST",
    headers: { Authorization: "Bearer sw_live_abc123..." },
  }
);
const { data } = await res.json();

Response

{
  "data": {
    "shipmentId": "clx2ship1",
    "refundStatus": "submitted",
    "trackingCode": "9400111899223100012345"
  }
}

The refundStatus reflects the carrier's response:

• submitted — refund request accepted
• refunded — refund completed (may take a few days)

Side Effects

• The shipment's status is set to voided and voidedAt is recorded
• The linked order's status is reset to pending
• A shipment.voided webhook event is dispatched

Errors