Returns and RMAs

Use this when a buyer sends items back and you need to record the return in Flxpoint, send the items back to the source that fulfilled them, and settle the refund and the source credit through the API.

Flxpoint splits a return into two records. A return belongs to an order and its channel: it lists what the buyer is sending back and what you refund them. An RMA (return merchandise authorization) belongs to a return and one source: it lists what goes back to that source, what the source approves, and what it credits you. RMA shipments then track the parcels going back.

A return can have several RMAs (totalRmas, rmas), one for each source the items go back to. An RMA has no fulfillment request id. To find the fulfillment request a returned item came from, follow the order line: a return item's orderItemId matches the orderItemId on the fulfillment request item that shipped it.

Identify the order with orderId or orderNumber (one of them is mandatory). items is required, and each item needs returnQuantity, returnReason, returnCondition, and either orderItemId or sku.

curl -X POST "https://api.flxpoint.com/returns" \
  -H "X-API-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": 551203,
    "returnNumber": "RET-1001",
    "items": [
      {
        "orderItemId": 8812045,
        "returnQuantity": 1,
        "returnReason": "Damaged in transit",
        "returnCondition": "Damaged",
        "refundedAmount": 24.99
      }
    ],
    "syncRefundChangesToOrder": false
  }'

When you omit title or salesPrice on an item, Flxpoint takes them from the order line. A 200 returns { "warning": ..., "return": { ... } }: read warning if it is set, and keep return.id and each return.items[].id for the next step. The response can also be 401, 404 or 409 Conflict.

On the return, refundSubtotal is the sum of the items' refundedAmount and refundTotal is refundSubtotal plus refundAdjustment. In the Flxpoint app, syncRefundChangesToOrder is the option to apply this amount to the channel invoice as a refund.

returnId, rmaNumber and returnToAddress are required. Send sourceId unless you are calling with that source's own Source token. Each item needs returnItemId and quantity; returnReason and condition default to the return item's values when you leave them out.

curl -X POST "https://api.flxpoint.com/rma" \
  -H "X-API-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "returnId": 70114,
    "sourceId": 1234,
    "rmaNumber": "RMA-1001-A",
    "returnToAddress": {
      "name": "Returns Dept",
      "companyName": "Acme Supply",
      "addressLine1": "100 Warehouse Way",
      "city": "Jacksonville",
      "stateCode": "FL",
      "postal": "32202",
      "countryCode": "US"
    },
    "items": [
      { "returnItemId": 90551, "quantity": 1, "cost": 12.50, "creditedAmount": 12.50 }
    ]
  }'

A 200 returns the Rma, including its id, rmaStatus and items[].id. A new RMA starts in Waiting. Set "autoApprove": true to approve the full quantity of every item at creation instead of running step 3.

If a return goes back to two sources, create two RMAs, each with its own sourceId and the return items that go to it. That is how the Flxpoint app does it.

Send the RMA's items with the quantities the source approves and denies. Only non-null fields are updated, and id (the RMA item id) is required on each.

curl -X PATCH "https://api.flxpoint.com/rmas/33017/items" \
  -H "X-API-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "id": 44120, "approvedQuantity": 1, "deniedQuantity": 0 }
  ]'

A 200 returns the updated Rma; read its rmaStatus. The Flxpoint app approves and denies through this call alone, sending each item's running totals rather than the change, and never sets rmaStatus by hand for it.

Two rules on this endpoint. approvedQuantity and deniedQuantity can only be updated while the RMA is Waiting or Partially Approved. And once either has been set, the item's quantity can no longer change, so fix quantities before you approve.

Identify the RMA with rmaId, or with rmaNumber. With an Account token, rmaNumber also needs sourceId (missing: 400; unknown source: 404). With a Source token, a sourceId that does not match the token returns 400. returnToAddress and shipment are required, and the shipment needs a trackingNumber. Tie each shipment item to its RMA item with rmaItemId; attachments take attachmentUrl and an attachmentType of packing_slip or shipping_label.

curl -X POST "https://api.flxpoint.com/rma-shipments" \
  -H "X-API-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rmaId": 33017,
    "returnToAddress": {
      "name": "Returns Dept",
      "addressLine1": "100 Warehouse Way",
      "city": "Jacksonville",
      "stateCode": "FL",
      "postal": "32202",
      "countryCode": "US"
    },
    "shipment": {
      "trackingNumber": "1Z999AA10123456784",
      "carrier": "UPS",
      "shipmentItems": [
        { "rmaItemId": 44120, "sku": "WIDGET-RED", "quantity": 1 }
      ]
    },
    "attachments": [
      { "attachmentUrl": "https://example.com/labels/rma-1001-a.pdf", "attachmentType": "shipping_label" }
    ]
  }'

A 200 returns the RmaShipment, which starts in Shipment Created. Keep its id and the ids under shipment.shipmentItems. When the parcel leaves, mark it sent; the call takes no body and returns 204:

curl -X PATCH "https://api.flxpoint.com/rma-shipments/5120/sent" \
  -H "X-API-TOKEN: YOUR_TOKEN"

When the source gets the parcel, record what arrived and what is written off. The body is an array; id is the RMA shipment item id (from shipment.shipmentItems[].id).

curl -X PATCH "https://api.flxpoint.com/rma-shipments/5120/receive" \
  -H "X-API-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "id": 77031, "rmaItemId": 44120, "receivedQuantity": 1, "voidedQuantity": 0 }
  ]'

The call returns 204. The Flxpoint app sends running totals here too: on a second receipt for the same item, send the new total received, not the extra units. Read the shipment, RMA or return back to see the result: rmaShipmentStatus on the shipment, receivedQuantity and voidedQuantity on the RMA items, and shipmentReceivedStatus on the RMA and the return.

The buyer's refund (return)

Set per-item refunds with PATCH /returns/{Id}/items (id required, plus refundedAmount) and an order-level adjustment with PATCH /returns/{id} (refundAdjustment). Then sync it:

curl -X PUT "https://api.flxpoint.com/returns/70114/sync-refund" \
  -H "X-API-TOKEN: YOUR_TOKEN"

This syncs the return's refund to the channel invoice for the order; refundLastSyncedAt on the return shows the last sync. In the Flxpoint app this call follows a successful refund on the order's payment.

The source's credit (RMA)

Set per-item credits with creditedAmount (step 2 or 3) and an adjustment with PATCH /rma/{id} (creditAdjustment); the RMA shows creditSubtotal, creditAdjustment and creditTotal. Then apply it to a source invoice:

curl -X PUT "https://api.flxpoint.com/rmas/33017/sync-credit" \
  -H "X-API-TOKEN: YOUR_TOKEN"

The order needs a source invoice first: the Flxpoint app blocks this action until one exists. The endpoint documents 200, 401, 404 and 500.

Close or cancel a return with PATCH /returns/{id} and {"returnStatus": "closed"} or "cancelled"; setting open re-opens a closed or cancelled return. Void or cancel an RMA with PATCH /rma/{id} and {"rmaStatus": "Voided"} or "Canceled". The Flxpoint app offers RMA and shipment actions only while the return is open, and follows these rules; mirror them in your integration:

• Void an RMA only while it is Waiting; cancel it once it is Approved, Partially Approved or Denied.
• Edit an RMA or sync its credit only while it is Waiting, Approved or Partially Approved.
• Mark a shipment sent only from Shipment Created; receive it only from Shipment Sent or Shipment Partially Received.

# Returns on an order, with their RMAs
curl -G "https://api.flxpoint.com/returns" \
  -H "X-API-TOKEN: YOUR_TOKEN" \
  --data-urlencode "orderId=551203" \
  --data-urlencode "includeRmas=true"

# Shipments for one RMA, with labels and the return address
curl -G "https://api.flxpoint.com/rma-shipments" \
  -H "X-API-TOKEN: YOUR_TOKEN" \
  --data-urlencode "rmaId=33017" \
  --data-urlencode "includeAttachments=true" \
  --data-urlencode "includeReturnAddress=true"

• GET /returns filters by orderId or channelId and pages with pageSize and pageNumber. RMAs are left out unless you pass includeRmas=true.
• GET /rma filters by returnId, sourceId, rmaNumbers (comma-separated), createdAfter and isAccountingSynced.
• GET /rma-shipments filters by rmaId, rmaNumbers and createdAfter.
• To catch changes, poll GET /orders with orderModifiedAfter: it matches orders whose returns or RMAs changed, and includeReturns=true adds the returns to each order.

If you sync RMAs to an accounting system, list the unsynced ones with GET /rma?isAccountingSynced=false and report the result with PATCH /rma/{id}: accountingSynced on success, accountingError with the message on failure.

• Moving an RMA to another source. PATCH /rma/{id} accepts rmaDestinationId; the Flxpoint app sends the new source's id there when you change an RMA's source.
• Approve or deny outside Waiting / Partially Approved. Not allowed; check rmaStatus first and do not retry the call unchanged.
• Fix a 400, don't loop on it. Read the error message, correct the body or wait for the right status, then send it again. Keep each token under 2 requests per second.
• Path names differ by endpoint. Returns and RMAs live under /returns, /rma, /rmas (items and credit sync) and /rma-shipments. Use each path exactly as listed below.

• Create Return (POST /returns)
• Get Returns (GET /returns)
• Get Return by ID (GET /returns/{id})
• Update Return (PATCH /returns/{id})
• Update Return Item (PATCH /returns/{Id}/items)
• Sync Return Refund to the Channel Invoice for the Order (PUT /returns/{returnId}/sync-refund)
• Create RMA (POST /rma)
• List Rmas (GET /rma)
• Get Rma By ID (GET /rma/{id})
• Update RMA (PATCH /rma/{id})
• Update RMA Items (PATCH /rmas/{rmaId}/items)
• Apply credit to a source invoice (PUT /rmas/{id}/sync-credit)
• Create RMA Shipment (POST /rma-shipments)
• List RMA Shipments (GET /rma-shipments)
• Get RMA Shipment By ID (GET /rma-shipments/{id})
• Set RMA Shipment as sent (PATCH /rma-shipments/{id}/sent)
• Receive RMA Shipment (PATCH /rma-shipments/{id}/receive)
• Get Orders (GET /orders) and Get Fulfillment Requests (GET /fulfillment-requests)