Create return request

Request a return for a delivered shipment.

Returns

POST/api/v1/scent/orders/{orderId}/return-requests

Partner self-serve: requests a return of one or more lines of a Delivered fulfilment group on your own order (orderId — the same Scent order GUID you already hold from order creation/tracking). Moves NO money by itself — the request is a pending-approval envelope around the existing return/refund execution chain; approval triggers the existing refund/ commission-clawback chain. Hard PRE-check eligibility gates (fail fast, before any human touches it): the group must be Delivered; each line’s quantity must be within its remaining returnable amount; the request must land within the configured return window (measured from the group’s delivery date); a line already carrying an unresolved Requested request cannot be requested again. You may withdraw the request yourself while it’s still Requested — see PATCH /api/v1/scent/return-requests/{id}/withdraw below. An order can ship as more than one parcel — fulfillmentGroupId in the request body identifies WHICH shipment the return is against (the same id you already have from the order-detail response’s fulfillmentGroups[].id).

Path parameters

orderIdstring (uuid)Required

The order’s own id (the Scent order’s own GUID — same as /api/v1/scent/orders/{orderId}).

Body parameters

fulfillmentGroupIdstring (uuid)Required

The specific shipment this return applies to (an order can ship as more than one parcel) — see fulfillmentGroups[].id on the order response.

linesarray of objectRequired

Response

idstring (uuid)

orderIdstring (uuid)

The order this return belongs to — the same Scent order GUID you already hold from order creation/tracking.

fulfillmentGroupIdstring (uuid)

returnRequestNumberstring

Human-facing RMA reference (e.g. “RMA-202608-000142”); null for a pre-RMA-lifecycle row.

statusstring (enum)

declineReasonstring

timeline.requestedAtstring (date-time)

timeline.decidedAtstring (date-time)

timeline.waybillIssuedAtstring (date-time)

timeline.collectionScheduledAtstring (date-time)

timeline.inTransitAtstring (date-time)

timeline.refundReleasedAtstring (date-time)

logistics.waybillNumberstring

logistics.carrierstring

logistics.carrierNameOtherstring

logistics.returnDestinationTypestring (enum)

The destination TYPE only — stamped once at first dispatch, immutable thereafter.

inspection.receivedAtstring (date-time)

inspection.inspectionStartedAtstring (date-time)

inspection.decidedAtstring (date-time)

inspection.outcomestring (enum)

Null until decided. The defect-vs-sound distinction (internal AcceptedDefect/AcceptedSound) collapses to Accepted here — that detail stays internal.

inspection.shippingFeeRefundAppliesboolean

Whether the order’s original shipping fee is refunded with this return — the amount itself is in refund.

refund.currencystring

refund.goodsobject

refund.commissionClawbacknumber (decimal)

Commission clawed back from your own earnings (a debit shown alongside the credit); null when the returned quantity carried no commission.

refund.shippingFeeRefundnumber (decimal)

The order’s shipping fee refunded on an accepted-defect return (VAT-inclusive); null otherwise — a separate wallet leg, not folded into total.

refund.totalnumber (decimal)

Your own actual goods-refund amount, VAT-inclusive gross (== goods.total).

linesarray of object

Other responses

400An invalid reasonCode, or VALIDATION_INVALID_REASON_CODE.

401No bearer token (UNAUTHORIZED_MISSING_TOKEN), an invalid token (UNAUTHORIZED_INVALID_TOKEN) or an expired one (UNAUTHORIZED_TOKEN_EXPIRED — mint a new token). UPSTREAM_AUTH_FAILED is different: a dependent service refused the Gateway itself. That is a server-side fault — retry later and do NOT re-mint your token. See the Errors guide.

403The route is not available to your credential (FORBIDDEN).

404Unknown order, fulfillment group, or order line (or cross-tenant order — no existence leak).

415The request body is not sent as application/json (UNSUPPORTED_MEDIA_TYPE).

422An eligibility rule failed.

429Too many requests — see the Rate limits guide. Retry after the Retry-After header (seconds).

502A dependent service returned an invalid response (BAD_GATEWAY). Retry with backoff.

503The service is temporarily unavailable (SERVICE_UNAVAILABLE). Retry with backoff.

504A dependent service did not respond in time (GATEWAY_TIMEOUT). Retry with backoff.

curl --request POST \
  --url https://api-omni.linra.net/api/v1/scent/orders/5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b/return-requests \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "fulfillmentGroupId": "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
    "lines": [
      {
        "scentOrderLineId": "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
        "allocationId": "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
        "quantity": 1,
        "reasonCode": "Damaged"
      }
    ]
  }'

const res = await fetch('https://api-omni.linra.net/api/v1/scent/orders/5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b/return-requests', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fulfillmentGroupId: '5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b',
    lines: [
      {
        scentOrderLineId: '5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b',
        allocationId: '5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b',
        quantity: 1,
        reasonCode: 'Damaged'
      }
    ]
  }),
});
const { payload } = await res.json();

var response = await httpClient.PostAsJsonAsync(
    "https://api-omni.linra.net/api/v1/scent/orders/5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b/return-requests",
    new
    {
        fulfillmentGroupId = "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
        lines = new[]
        {
            new
            {
                scentOrderLineId = "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
                allocationId = "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
                quantity = 1,
                reasonCode = "Damaged"
            }
        }
    });

var envelope = await response.Content.ReadFromJsonAsync<ApiResponse<PartnerReturnRequestResponse>>();

Response

{
  "state": "SUCCESS",
  "payload": {
    "id": "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
    "orderId": "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
    "fulfillmentGroupId": "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
    "returnRequestNumber": "string",
    "status": "Requested",
    "declineReason": "string",
    "timeline": {
      "requestedAt": "2026-08-22T09:14:03Z",
      "decidedAt": "2026-08-22T09:14:03Z",
      "waybillIssuedAt": "2026-08-22T09:14:03Z",
      "collectionScheduledAt": "2026-08-22T09:14:03Z",
      "inTransitAt": "2026-08-22T09:14:03Z",
      "refundReleasedAt": "2026-08-22T09:14:03Z"
    },
    "logistics": {
      "waybillNumber": "string",
      "carrier": "string",
      "carrierNameOther": "string",
      "returnDestinationType": "SortingPoint"
    },
    "inspection": {
      "receivedAt": "2026-08-22T09:14:03Z",
      "inspectionStartedAt": "2026-08-22T09:14:03Z",
      "decidedAt": "2026-08-22T09:14:03Z",
      "outcome": "Accepted",
      "shippingFeeRefundApplies": true
    },
    "refund": {
      "currency": "SAR",
      "goods": {
        "net": 0,
        "vat": 0,
        "total": 0
      },
      "commissionClawback": 0,
      "shippingFeeRefund": 0,
      "total": 0
    },
    "lines": [
      {
        "id": "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
        "scentOrderLineId": "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
        "allocationId": "5b1e3a1c-9d2e-4f3a-8b1c-9f0a2e3d4c5b",
        "quantity": 0,
        "reasonCode": "string"
      }
    ]
  },
  "details": null
}