Set up FLIPR and connect it to your systems

Search returns, newest first.

{
  "returns": [
    {
      "id": "FLP-40318827",
      "channel_order_id": "88201",
      "customer_name": "Sam Carter",
      "customer_email": "[email protected]",
      "postcode": "M1 4AB",
      "channel_source": "SHOPIFY",
      "status": "received",
      "return_tracking": "AB123456789GB",
      "carrier": "Royal Mail",
      "provider": null,
      "created_at": "2026-10-01 09:14:22",
      "completed_at": null,
      "item_count": 1,
      "items": [
        { "sku": "TS-BLK-M", "name": "Black T-shirt", "action": "refund", "exchangeSku": null, "qty": 1 }
      ],
      "link": "https://getflipr.app/return/FLP-40318827"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "pages": 1 }
}

One return with every field, its items, the latest 20 activity entries (action, detail, user, at) and, when the shopper started it in the portal, the linked returnRequest.

Create a return. It starts with the status received.

curl -X POST https://api.getflipr.app/api/v1/returns \
  -H "Authorization: Bearer flpr_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "orderNumber": "88201",
    "customerName": "Sam Carter",
    "customerEmail": "[email protected]",
    "items": [{ "sku": "TS-BLK-M", "name": "Black T-shirt", "qty": 1, "action": "refund" }]
  }'

Responds 201:

{ "ok": true, "returnId": "FLP-40318827", "status": "received", "items": 1,
  "link": "https://getflipr.app/return/FLP-40318827" }

Update a return. Send only the fields you want to change: status, notes, returnTracking, carrier, provider, processedBy. Setting status to completed records the completion time.

{ "ok": true, "id": "FLP-40318827", "status": "completed" }

Book the return in Linnworks: creates the RMA and puts the stock back, or scraps it where your scrap rules say so. The return must have a Linnworks order linked. Send no body to process every item, or { "items": [{ "sku", "action", "qty" }] } to process some.

The response lists processed, alreadyProcessed and errors by SKU. Calling it again is safe: items already booked are reported in alreadyProcessed and not booked twice.

Send the customer's money back for the items on the return marked refund. FLIPR refunds the same way the dashboard does: a Shopify order is refunded on Shopify and a WooCommerce order on WooCommerce, both to the original payment, and any other order through Linnworks, which passes the refund to the sales channel. The key must have Allow refunds turned on.

curl -X POST https://api.getflipr.app/api/v1/returns/FLP-40318827/refund \
  -H "Authorization: Bearer flpr_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 12.50 }'

{ "ok": true, "returnId": "FLP-40318827", "via": "shopify",
  "amount": 12.5, "currency": "GBP", "refundId": "gid://shopify/Refund/…" }

The customer has been refunded only when the response is 200 with "ok": true. Anything else means no money moved, and error says why.

• 403: the key is not allowed to refund.
• 409 with alreadyRefunded: the return was refunded before. Nothing is refunded twice unless you send allowAdditional. For a WooCommerce order it can also mean the items were already refunded on WooCommerce itself, which allowAdditional does not override.
• 409 with inProgress: another refund call for this return is still running. Wait, then read the return.
• 422: Shopify, WooCommerce, Linnworks or the sales channel refused the refund.

If a call times out, read the return before trying again: refund_status is processed once a refund has gone through. When you create a return for a Shopify or WooCommerce order, pass the channel from the order search as channelSource so FLIPR knows where to refund it.

Search your Linnworks orders by order number, email or reference. q is required, and Linnworks must be connected.

{
  "orders": [
    {
      "linnworksOrderId": "3f2b…",
      "orderNumber": "100234",
      "channelOrderId": "88201",
      "customerName": "Sam Carter",
      "customerEmail": "[email protected]",
      "postcode": "M1 4AB",
      "channel": "SHOPIFY",
      "status": "…",
      "orderDate": "2026-09-20T10:02:00Z",
      "tracking": "…",
      "country": "United Kingdom",
      "items": [{ "sku": "TS-BLK-M", "name": "Black T-shirt", "qty": 1, "price": 18, "rowId": "…" }]
    }
  ]
}

One order with its lines, by the linnworksOrderId from the search. Use it to take a return against an order: it says what was paid for each line and how much of it is already back.

{
  "linnworksOrderId": "3f2b…",
  "orderNumber": 100234,
  "channelOrderId": "88201",
  "customerName": "Sam Carter",
  "customerEmail": "[email protected]",
  "channel": "shopify",
  "channelSub": "My Store",
  "status": "dispatched",
  "orderDate": "2026-09-20T10:02:00Z",
  "currency": "GBP",
  "items": [
    { "rowId": "…", "sku": "TS-BLK-M", "name": "Black T-shirt", "qty": 2, "lineTotal": 32.4, "returnedQty": 1, "imageUrl": "https://…" }
  ]
}

• lineTotal is what the customer paid for the whole line, VAT included, after discounts. Divide by qty for one unit.
• returnedQty is how many units of the line are already booked back in Linnworks. Returns still on their way are not counted.
• status is dispatched or open. An open order has not shipped, so it cannot be returned yet.
• imageUrl is null when the product has no image.
• 404: no order with that ID in your Linnworks.

Search requests, newest first. q matches order number, customer name, email or request ID. limit defaults to 10, maximum 50.

Each entry in requests has id, order_number, customer_name, customer_email, status, return_action, return_reason, carrier, tracking_number, label_url, label_cost, created_at, updated_at and a link to it in the dashboard.

One request with every field, its items, and payment (amount, status, paid, paidAt) when the shopper paid for the label.

Carrier tracking events for a parcel, newest first. Results are cached for five minutes; add ?refresh=1 to fetch fresh data. The carrier is detected from the number; pass ?provider= if you already know it.

{
  "trackingNumber": "AB123456789GB",
  "provider": "royal_mail_api",
  "carrier": "Royal Mail",
  "latestStatus": "in_transit",
  "latestStatusLabel": "🚚 In transit",
  "events": [
    { "status": "in_transit", "statusLabel": "🚚 In transit", "description": "…",
      "location": "…", "timestamp": "2026-10-02T08:30:00Z", "provider": "royal_mail_api" }
  ],
  "cached": false,
  "fetchedAt": "2026-10-02T09:00:00Z"
}