Returns

Create and manage return requests: approve or deny them, buy the return shipping label, mark the package received, and refund the shopper.

A return is a shopper's request to send back items from one of your orders. Shoppers can open returns themselves in your ShipWave returns portal, and you can create them with this API. Both kinds appear in the same list and follow the same lifecycle.

Scopes: GET endpoints need read:returns. POST and PUT need write:returns. A Shipping API key (read:*, write:*) has both. See Authentication.

Return responses can include fields that aren't listed on this page. Rely only on the documented fields; undocumented fields can change or be removed without notice.

Every endpoint sees only the returns and orders on your account. A return ID that belongs to another account returns 404 NOT_FOUND, the same as an ID that doesn't exist.

These endpoints don't send webhook events. Poll Get Return to follow a return.

Return Lifecycle

pending ──approve──▶ approved ──label──▶ label_created ──delivered or receive──▶ received ──refund──▶ refunded
   │                                                                                     └──────────▶ no_action_needed ($0)
   └──deny──▶ denied

A delivered return label moves the return to received from label_created or shipped. If the label of an expired or cancelled return is delivered anyway, the return reopens as received. A delivery never refunds the shopper automatically. ShipWave emails you, and you refund with Refund Return.

Return Shipping and Labels

When you call Create Return Label, ShipWave rates the parcel from the shopper's address to your return warehouse, buys the cheapest available rate right away, and returns the label URLs. It doesn't email the label to the shopper. Send labelUrl (or the PDF or PNG version) to the shopper yourself. Calling it again for the same return returns the same label; it never buys a second one unless you ask it to replace the first.

The shopper doesn't pay anything when the label is created. If your return policy doesn't offer free returns, ShipWave records a return shipping fee on the return (shippingFeeCharged) when the label is purchased, and deducts it from the shopper's refund. International returns always carry a return shipping fee, even when your policy offers free returns. When the return ships free, the fee is 0.

Shopper Notifications

Creating, approving, denying, labeling, and receiving a return don't email the shopper. Refund Return emails the shopper a refund receipt when it issues a refund greater than $0 (except for Walmart returns, which Walmart refunds).

The Return Object

Get Return returns these fields. List Returns returns a subset.

Item object:

Items created with this API store only these fields and an optional reason. Items from your returns portal or a connected marketplace can carry other fields.

---

List Returns

GET /api/v1/returns

Returns a page of your returns, most recently requested first, plus a count of all your returns by status.

Response shape: unlike other list endpoints, this one doesn't use the standard data/meta envelope. The page of returns is in returns, the paging info is in pagination, and the per-status totals are in counts. The page and limit parameters work as described in Pagination.

Query Parameters

Example

curl "https://shipwave.app/api/v1/returns?status=label_created&limit=25" \
  -H "Authorization: Bearer sw_live_abc123..."

const res = await fetch(
  "https://shipwave.app/api/v1/returns?status=label_created&limit=25",
  { headers: { Authorization: "Bearer sw_live_abc123..." } }
);
const { returns, pagination, counts } = await res.json();

Response

{
  "returns": [
    {
      "id": "clx7ret1",
      "orderNumber": "#1042",
      "customerEmail": "jane@example.com",
      "customerName": "Jane Doe",
      "status": "label_created",
      "reason": "defective",
      "reasonDetail": "Left side stopped working after two days",
      "items": [
        {
          "lineItemId": "clx1item1",
          "sku": "WIDGET-001",
          "name": "Blue Widget",
          "quantity": 1,
          "price": 49.99
        }
      ],
      "refundAmount": null,
      "shippingFeeCharged": 0,
      "restockingFeeCharged": 0,
      "returnTrackingNumber": "9400111899223100012345",
      "returnCarrier": "USPS",
      "requestedAt": "2026-10-05T16:12:44.000Z",
      "approvedAt": "2026-10-05T18:02:10.000Z",
      "deniedAt": null,
      "shippedAt": null,
      "receivedAt": null,
      "refundedAt": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 1,
    "totalPages": 1
  },
  "counts": {
    "all": 14,
    "pending": 2,
    "approved": 1,
    "label_created": 3,
    "shipped": 0,
    "received": 1,
    "no_action_needed": 0,
    "expired": 1,
    "invoice_created": 0,
    "invoice_sent": 0,
    "refunded": 5,
    "denied": 1,
    "cancelled": 0,
    "exchanged": 0
  }
}

pagination.total counts the returns that match your filters. counts always covers every return on your account and ignores status and search. It has a key for every status in Return Lifecycle, and the per-status counts add up to all.

For 401, 403, and 429 responses, see Errors.

---

Create Return

POST /api/v1/returns

Creates a return in pending status. ShipWave looks up the order by orderNumber, checks the request against your return window, and saves a copy of your return policy terms on the return. The restocking fee rate ShipWave later deducts comes from that copy, so changing your return policy doesn't re-price returns that are already open.

Request Body

Item fields:

Other item fields are dropped. Text fields can be up to 500 characters.

returnWindowOverride object:

Things to know:

• The order must exist on your account. If no order matches orderNumber, the request fails with 404 NOT_FOUND and no return is created.
• Later steps depend on the items. Create Return Label needs each item's sku to match a product with a weight on file, and Refund Return needs a price above $0 for each item (sent with the item, or resolved from the order line).
• The return window is your return policy's window (30 days if you haven't set one). It starts on the order's latest carrier-confirmed delivery date, or the order date when there's no delivery, and counts calendar days: the last day ends at 11:59:59 PM in the timeZone shown in the response (currently America/New_York for every store). A return requested after that needs either an active override from Reopen Return Window or a confirmed returnWindowOverride; otherwise the request fails with 409 CONFLICT. An override is ignored for an order still inside its window.

Example

curl -X POST https://shipwave.app/api/v1/returns \
  -H "Authorization: Bearer sw_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "orderNumber": "#1042",
    "customerEmail": "jane@example.com",
    "customerName": "Jane Doe",
    "reason": "defective",
    "reasonDetail": "Left side stopped working after two days",
    "items": [
      { "lineItemId": "clx1item1", "sku": "WIDGET-001", "name": "Blue Widget", "quantity": 1 }
    ],
    "itemCondition": "unopened"
  }'

const res = await fetch("https://shipwave.app/api/v1/returns", {
  method: "POST",
  headers: {
    Authorization: "Bearer sw_live_abc123...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    orderNumber: "#1042",
    customerEmail: "jane@example.com",
    customerName: "Jane Doe",
    reason: "defective",
    reasonDetail: "Left side stopped working after two days",
    items: [
      { lineItemId: "clx1item1", sku: "WIDGET-001", name: "Blue Widget", quantity: 1 },
    ],
    itemCondition: "unopened",
  }),
});
const { data } = await res.json(); // 201 Created

Response (201 Created)

{
  "data": {
    "id": "clx7ret1",
    "orderNumber": "#1042",
    "customerEmail": "jane@example.com",
    "customerName": "Jane Doe",
    "status": "pending",
    "reason": "defective",
    "reasonDetail": "Left side stopped working after two days",
    "items": [
      { "lineItemId": "clx1item1", "sku": "WIDGET-001", "name": "Blue Widget", "quantity": 1 }
    ],
    "itemCondition": "unopened",
    "restockingFeePercent": 10,
    "requestedAt": "2026-10-05T16:12:44.000Z",
    "returnWindow": {
      "deliveredAt": "2026-09-28T19:03:00.000Z",
      "returnDeadline": "2026-10-29T03:59:59.999Z",
      "returnDeadlineDate": "2026-10-28",
      "timeZone": "America/New_York",
      "returnWindowDays": 30,
      "daysOutsideWindow": 0,
      "exceptionApplied": false
    },
    "order": {
      "id": "clx1ord1",
      "orderNumber": "#1042",
      "totalValue": 54.43
    }
  }
}

Errors

Return window conflict:

{
  "error": {
    "code": "CONFLICT",
    "message": "This order is past the 30-day return window. To approve an exception, confirm the policy override and provide a reason.",
    "details": {
      "deliveredAt": "2026-08-20T17:45:00.000Z",
      "returnDeadline": "2026-09-20T03:59:59.999Z",
      "returnDeadlineDate": "2026-09-19",
      "timeZone": "America/New_York",
      "returnWindowDays": 30,
      "daysOutsideWindow": 16,
      "overrideRequired": true
    }
  }
}

For 401, 403, and 429 responses, see Errors.

---

Get Return

GET /api/v1/returns/:id

Returns one return with its linked order and return shipment.

Example

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

Response

{
  "data": {
    "id": "clx7ret1",
    "orderNumber": "#1042",
    "orderDate": "2026-09-24T14:31:07.000Z",
    "customerEmail": "jane@example.com",
    "customerName": "Jane Doe",
    "status": "label_created",
    "reason": "defective",
    "reasonDetail": "Left side stopped working after two days",
    "items": [
      {
        "lineItemId": "clx1item1",
        "sku": "WIDGET-001",
        "name": "Blue Widget",
        "quantity": 1,
        "price": 49.99
      }
    ],
    "refundAmount": null,
    "shippingFeeCharged": 0,
    "restockingFeeCharged": 0,
    "returnTrackingNumber": "9400111899223100012345",
    "returnCarrier": "USPS",
    "returnLabelUrl": "https://files.example.com/labels/clx7ret1.png",
    "adminNotes": "[2026-10-05 18:02:10] Note: Approved: defect confirmed from photos",
    "denialReason": null,
    "requestedAt": "2026-10-05T16:12:44.000Z",
    "approvedAt": "2026-10-05T18:02:10.000Z",
    "deniedAt": null,
    "labelCreatedAt": "2026-10-05T18:04:31.000Z",
    "shippedAt": null,
    "receivedAt": null,
    "refundedAt": null,
    "order": {
      "id": "clx1ord1",
      "orderNumber": "#1042",
      "totalValue": 54.43,
      "lineItems": [
        {
          "id": "clx1item1",
          "sku": "WIDGET-001",
          "name": "Blue Widget",
          "quantity": 1,
          "weight": 16,
          "price": 49.99,
          "imageUrl": "https://cdn.shopify.com/s/files/1/widget-blue.jpg"
        }
      ]
    },
    "returnShipment": {
      "id": "clx2ship9",
      "trackingCode": "9400111899223100012345",
      "trackingStatus": "pre_transit",
      "carrier": "USPS",
      "service": "GroundAdvantage"
    }
  }
}

order.lineItems lists every line on the order, not only the returned items, with the same fields as order lines in the Orders API. returnShipment.id is a shipment ID you can use with the Shipments API.

Errors

For 401, 403, and 429 responses, see Errors.

---

Add Return Note

PUT /api/v1/returns/:id

Adds a note to the return's internal notes, in any status. Notes are a log: your note is appended as a new timestamped Note: line, and existing notes, including the entries ShipWave writes when it refunds a return, are never replaced or removed. A note identical to the last line isn't added twice.

Request Body

Other fields are ignored, except refundAmount, which is rejected. Use Refund Return to refund. Notes can't be cleared, so null is rejected.

Example

curl -X PUT https://shipwave.app/api/v1/returns/clx7ret1 \
  -H "Authorization: Bearer sw_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "adminNotes": "Shopper sent photos of the defect" }'

Response

{
  "data": {
    "id": "clx7ret1",
    "adminNotes": "[2026-10-05 16:20:03] Note: Shopper sent photos of the defect",
    "refundAmount": null
  }
}

Errors

For 401, 403, and 429 responses, see Errors.

---

Approve Return

POST /api/v1/returns/:id/approve

Approves a pending return and moves it to approved. Approving doesn't buy a label or set the refund amount.

If the return was requested after its return window closed and no exception was recorded when it was created, you need to confirm one now with returnWindowOverride, unless the order has an active override from Reopen Return Window. The window is checked in the timezone recorded when the return was created.

Only a return that is still pending is approved. If another request approves or denies it first, you get 409 CONFLICT.

Request Body

All fields are optional, and the body can be empty.

A body that includes refundAmount is rejected.

Example

curl -X POST https://shipwave.app/api/v1/returns/clx7ret1/approve \
  -H "Authorization: Bearer sw_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "adminNotes": "Approved: defect confirmed from photos" }'

Response

{
  "data": {
    "id": "clx7ret1",
    "status": "approved",
    "approvedAt": "2026-10-05T18:02:10.000Z",
    "refundAmount": null
  }
}

Errors

For 401, 403, and 429 responses, see Errors.

---

Deny Return

POST /api/v1/returns/:id/deny

Denies a pending return and moves it to denied. The shopper isn't notified. If another request approves or denies the return first, you get 409 CONFLICT.

Request Body

Example

curl -X POST https://shipwave.app/api/v1/returns/clx7ret1/deny \
  -H "Authorization: Bearer sw_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "denialReason": "Item was used and is outside the return policy" }'

Response

{
  "data": {
    "id": "clx7ret1",
    "status": "denied",
    "deniedAt": "2026-10-05T18:02:10.000Z",
    "denialReason": "Item was used and is outside the return policy"
  }
}

Errors

For 401, 403, and 429 responses, see Errors.

---

Create Return Label

POST /api/v1/returns/:id/label

Buys a prepaid 4×6 return label from the shopper to your return warehouse and moves the return to label_created. The return must be approved (or already label_created, below) and linked to an order. See Return Shipping and Labels for how the label is paid for and delivered.

How ShipWave builds the shipment:

• From: customerAddress if you send it. Otherwise the ship-to address of the order's first shipment, with the return's customerName. If your customerAddress has no phone, ShipWave uses the phone on the order's shipping address. When the shopper has no phone at all, your return warehouse's phone goes on the label instead, because carriers such as FedEx require one.
• To: your default warehouse, if it has a complete address. Otherwise the first warehouse, alphabetically by name, that has one. The label always goes to one of your own warehouses; you can't choose another destination.
• Parcel: the weight and dimensions you send. Otherwise the box the shopper described in the returns portal, then the catalog weight and dimensions of the returned items. Every returned item that requires shipping must have a SKU that matches a product with a weight on file, even when you send parcelWeight.
• Rate: the cheapest available rate. FedEx is skipped when either phone number isn't a valid US or Canada number. International returns include customs paperwork, which needs an HS code, country of origin, weight, and value for every item (see Products).

Calling this endpoint again is safe:

• The return already has a label (label_created): you get that label back with idempotent: true, and nothing is bought. labelPdfUrl and labelPngUrl are null and allRates is empty in that response.
• To replace the label, send replaceExistingLabel: true. ShipWave voids the current label with the carrier first and then buys a new one. If the carrier won't void it (for example, the package is already moving), the request fails with 409 CONFLICT and nothing is bought.
• Two requests at once: only one buys a label. The other gets 409 CONFLICT.

Request Body

All fields are optional, and the body can be empty.

Parcel values must be positive numbers; 0 is ignored.

customerAddress object:

When you send customerAddress, it must include street1, city, state, and zip, and every field must be a string. The carrier validates the address itself when it rates the shipment.

Example

curl -X POST https://shipwave.app/api/v1/returns/clx7ret1/label \
  -H "Authorization: Bearer sw_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerAddress": {
      "name": "Jane Doe",
      "street1": "742 Evergreen Ter",
      "city": "Springfield",
      "state": "OR",
      "zip": "97477",
      "country": "US",
      "phone": "541-555-0123"
    }
  }'

Response

This example is for a store whose return policy offers free returns, so shippingFee is 0:

{
  "data": {
    "label": {
      "trackingNumber": "9400111899223100012345",
      "carrier": "USPS",
      "service": "GroundAdvantage",
      "labelUrl": "https://files.example.com/labels/clx7ret1.png",
      "labelPdfUrl": null,
      "labelPngUrl": "https://files.example.com/labels/clx7ret1.png",
      "shippingFee": 0,
      "isInternational": false,
      "returnedGoodsTreatment": null,
      "customerPaysReturnShipping": false,
      "originalShippingRefundable": false,
      "customsFormUrl": null,
      "customsFormType": null,
      "customsFormSubmittedElectronically": null
    },
    "allRates": [
      {
        "carrier": "USPS",
        "service": "GroundAdvantage",
        "deliveryDays": 3
      },
      {
        "carrier": "UPS",
        "service": "Ground",
        "deliveryDays": 4
      }
    ],
    "idempotent": false,
    "replacedLabel": null
  }
}

Errors

For 401, 403, and 429 responses, see Errors.

---

Mark Return Received

POST /api/v1/returns/:id/receive

Marks a label_created or shipped return as received. Returns that use a ShipWave label are usually marked received automatically when the carrier reports delivery, so you mostly need this for packages that arrive before tracking updates. Receiving doesn't refund the shopper.

Request Body

The body can be empty.

Example

curl -X POST https://shipwave.app/api/v1/returns/clx7ret1/receive \
  -H "Authorization: Bearer sw_live_abc123..."

Response

{
  "data": {
    "id": "clx7ret1",
    "status": "received",
    "receivedAt": "2026-10-09T15:40:22.000Z"
  }
}

Errors

For 401, 403, and 429 responses, see Errors.

---

Refund Return

POST /api/v1/returns/:id/refund

Refunds a received return. ShipWave calculates the amount; you can't send one.

refund = returned items + sales tax on those items − restocking fee − return shipping fee

• Returned items are valued at the price the shopper paid, after discounts.
• Sales tax on the returned items is confirmed against the Shopify order.
• Restocking fee is a percentage of the items plus tax, at the rate saved on the return when it was created, so a later policy change doesn't re-price it. If your policy charges different rates for unopened and opened items, the item condition picks the saved rate, and a return with no condition recorded uses the opened rate. Only an older return with no saved rate uses your current policy rate. A restocking fee you already changed in the ShipWave dashboard is kept. Before ShipWave deducts a restocking fee, the return needs an inspection recorded in the ShipWave dashboard, or you must confirm skipping it with inspectionSkip.
• Return shipping fee is the fee recorded on the return (shippingFeeCharged), normally set when the return label was purchased.

A refund above $0 is issued on the linked Shopify order to the original payment method, the return moves to refunded, and ShipWave emails the shopper a receipt under your store name (your return policy's merchant name). When nothing is owed after fees, no refund is issued, no email is sent, and the return moves to no_action_needed.

Returns from a connected Walmart channel are refunded through Walmart for the returned items' amount, with no fees deducted. feeOverride and inspectionSkip are ignored for them, and the response includes a walmartRefund object.

Each return can be refunded once, and retrying is safe:

• After a refund succeeded, a retry returns the stored result with idempotent: true, and the shopper isn't refunded again.
• After Shopify rejected a refund (422, Shopify refund failed: ...), fix the cause and call again. Before retrying, ShipWave checks the order's refunds in Shopify. If the failed attempt made no refund, it refunds now. If Shopify shows that the attempt did refund the shopper, ShipWave records that refund and closes the return without refunding twice (idempotent: true). If Shopify shows a refund ShipWave can't match to the attempt, nothing is refunded and you get 409 CONFLICT; contact ShipWave support to reconcile the return.
• While an attempt is still in progress, other calls return 409 CONFLICT. Wait and fetch the return before trying again.

Request Body

All fields are optional, and the body can be empty.

Bodies that include finalRefundAmount, refundAmount, or amount are rejected.

feeOverride object:

Fees can't add up to more than the returned items plus tax. Fee overrides aren't allowed on a return-first exchange from the returns portal, where the refund is only the price difference owed to the shopper.

inspectionSkip object:

Example

curl -X POST https://shipwave.app/api/v1/returns/clx7ret1/refund \
  -H "Authorization: Bearer sw_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "inspectionSkip": {
      "confirmed": true,
      "reason": "Checked on arrival; box unopened"
    }
  }'

Response

{
  "data": {
    "id": "clx7ret1",
    "status": "refunded",
    "refundedAt": "2026-10-09T16:05:12.000Z",
    "itemsSubtotal": 49.99,
    "itemsTax": 4.44,
    "defaultShippingFee": 0,
    "defaultRestockingFee": 5.44,
    "shippingFeeDeducted": 0,
    "restockingFeeDeducted": 5.44,
    "finalRefundAmount": 48.99,
    "feeOverrideApplied": false,
    "inspectionSkipped": true,
    "shopifyRefundId": "1029384756",
    "refundReceiptEmailSent": true,
    "dutyRefund": null,
    "idempotent": false
  }
}

A replayed response (idempotent: true) has the same fields as the first one. A Walmart refund response doesn't include itemsTax or inspectionSkipped.

Errors

For 401, 403, and 429 responses, see Errors.

---

Get Return Window

GET /api/v1/returns/window-overrides?orderNumber=:orderNumber

Shows one order's return window, any active window override, any open return, and your returns portal link. Use it before Reopen Return Window.

Query Parameters

Example

curl "https://shipwave.app/api/v1/returns/window-overrides?orderNumber=1007" \
  -H "Authorization: Bearer sw_live_abc123..."

Response

{
  "data": {
    "order": {
      "id": "clx1ord2",
      "orderNumber": "#1007"
    },
    "returnWindow": {
      "returnDeadline": "2026-09-20T03:59:59.999Z",
      "returnDeadlineDate": "2026-09-19",
      "isOutsideWindow": true,
      "daysOutsideWindow": 16
    },
    "activeOverride": null,
    "openReturn": null,
    "portalUrl": "https://shipwave.app/returns/acme"
  }
}

Errors

For 401, 403, and 429 responses, see Errors.

---

Reopen Return Window

POST /api/v1/returns/window-overrides

Reopens your returns portal for one order whose return window has closed, so the shopper can submit the return themselves. The override lasts through the end of the 14th calendar day after you grant it. While it's active, Create Return and Approve Return accept the order's late return through the API too, without a returnWindowOverride.

• Already reopened: if the order has an active override, you get that override back (200 OK, alreadyActive: true) and no new one is created.
• Still inside its window: the shopper can already use the portal, so no override is created and you get 409 CONFLICT with the window's state in details.

Request Body

Example

curl -X POST https://shipwave.app/api/v1/returns/window-overrides \
  -H "Authorization: Bearer sw_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "orderNumber": "#1007",
    "reason": "Defective unit reported after the window closed",
    "reference": "Ticket 4821"
  }'

Response (201 Created)

The same fields as Get Return Window, plus alreadyActive and granted. When the order already had an active override, the status is 200 OK, alreadyActive is true, and granted describes that existing override.

{
  "data": {
    "order": {
      "id": "clx1ord2",
      "orderNumber": "#1007"
    },
    "returnWindow": {
      "returnDeadline": "2026-09-20T03:59:59.999Z",
      "returnDeadlineDate": "2026-09-19",
      "isOutsideWindow": true,
      "daysOutsideWindow": 16
    },
    "activeOverride": {
      "id": "clx8ovr1",
      "grantedAt": "2026-10-05T16:30:00.000Z",
      "expiresAt": "2026-10-20T03:59:59.999Z",
      "reason": "Defective unit reported after the window closed",
      "reference": "Ticket 4821"
    },
    "openReturn": null,
    "portalUrl": "https://shipwave.app/returns/acme",
    "alreadyActive": false,
    "granted": {
      "id": "clx8ovr1",
      "grantedAt": "2026-10-05T16:30:00.000Z",
      "expiresAt": "2026-10-20T03:59:59.999Z",
      "days": 14
    }
  }
}

Errors

For 401, 403, and 429 responses, see Errors.