How do I track device RMA and return shipments by API?

Watch each return label's tracking number with POST /v1/watches and put the RMA in metadata. lastscanned re-checks it on its own schedule and sends a signed tracking.updated webhook, with your metadata attached, on the first carrier scan, every status change and delivery back to you, so the RMA can move from "label sent" to "in transit" to "received" without anyone checking a carrier site. Pro is $4.99/mo for 1,000 unique numbers, then $0.015 each, with no daily limit. A free key tracks 5 numbers a day. With no key you get 1 lookup a day, then pay per request over MPP: $0.50 by card for a 25-number pack, or $0.02 a number in USDC on Tempo.

Try it

curl: watch a return label with its RMA
curl -X POST https://api.lastscanned.com/v1/watches \
  -H "Authorization: Bearer lsk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trackingNumber": "1Z54V8630394427740", "metadata": {"rma": "RMA-1042", "leg": "return"}}'
Node: move the RMA when the carrier scans
// after checking the Lastscanned-Signature header (see the webhooks docs)
export async function onLastscanned(event) {
  if (event.type !== "tracking.updated") return;
  const { watch, result } = event.data;
  const rma = watch.metadata.rma;
  if (result.status === "in_transit") await setRmaState(rma, "in_transit", result.events[0]?.timestamp);
  if (result.status === "delivered") await setRmaState(rma, "received", result.deliveredAt);
  if (result.status === "exception") await flagRma(rma, result.statusDescription);
}

Ways to follow returned devices

OptionHow it worksPriceNotes
Check carrier sites by handOpen each return number on UPS, FedEx or USPS.FreeSlow, and nobody notices a label that was never used.
Poll from your RMA systemRe-track open RMAs on a schedule, 35 numbers per request.On Pro re-checks are freeYou keep the schedule and compare results.
Watches + webhookPOST /v1/watches with the RMA in metadata; your endpoint gets each change.Each return counts onceEnds on delivery, or after 14 days with no carrier record.

Details

Labels that were never used

A return label that never gets a carrier scan ends its watch as not_found after 14 days and sends watch.ended, which is the moment to chase the customer.

Long return windows

A watch lasts up to 90 days, which covers 30- and 45-day return windows from the day the label is issued.

Outbound replacements too

Watch the replacement's outbound number with leg: outbound in metadata, and the same handler can tell the customer when it is out for delivery.

What it costs

On Pro each number counts once a month however often it is re-checked. 1,200 return labels in a month is $4.99 + 200 × $0.015 = $7.99.

Watch your first returns free

FAQ

Can I attach an RMA number to a tracking number?
Yes. Put it in the watch's metadata (up to 2 KB of JSON) and it comes back on every webhook.
Which carriers work for return labels?
Any of 549, including UPS, FedEx and USPS return labels.
What if the customer never ships the device?
The watch ends as not_found after 14 days without a carrier record, and you get watch.ended.
Can I add a batch of RMAs at once?
Yes. POST /v1/watches takes up to 100 numbers per call, or paste a list on app.lastscanned.com/watches.