Scent fulfilment for vendors

This page walks the whole physical-fulfilment story end to end, from the moment an order lands on you to a possible return, and documents every status/enum value you’ll ever see on the way. The step-by-step mechanics (exact requests/responses, error codes) live in their own guides — Orders & fulfilment status and Returns — this page is the map that ties them together; go there for the wire-level detail.

Every action below requires your credential to hold the Orders capability. See Authentication & capabilities for how capabilities work.

The whole flow

flowchart TD
    A["Order assigned to you<br/>fulfilment group: Pending"] --> B{"Sourced yet?"}
    B -->|"no (manual sourcing)"| A0["PendingSourcing"] --> A
    B -->|yes| C["You pack it<br/>(Linra staff marks Packed —<br/>you never push this yourself)"]
    C --> D["You push Shipped<br/>carrier + trackingRef required"]
    D --> E["You push Delivered"]
    A -->|"you push Cancelled"| X["Cancelled"]
    D -->|"you push Cancelled"| X
    E --> F{"Partner requests<br/>a return?"}
    F -->|no| Done["Done"]
    F -->|"yes, shipped to you directly (model A)"| G["Return assigned to you"]
    G --> H["PATCH .../received<br/>InTransit -> Received"]
    H --> I["PATCH .../inspection/start<br/>Received -> UnderInspection"]
    I --> J["POST .../evidence<br/>at least one Photo required"]
    J --> K["PATCH .../inspection/propose<br/>your outcome — never authoritative"]
    K --> L{"Linra staff<br/>decides"}
    L -->|AcceptedDefect or AcceptedSound| M["InspectionAccepted<br/>refund/clawback executes"]
    L -->|Rejected| N["InspectionRejected — terminal"]
    K -.no decision within window.-> M2["Auto-accepted as defect<br/>(silence timeout)"]
    E -.fully returned.-> R["Group status becomes Returned"]
    M --> R
    M2 --> R

Receiving an assigned order

GET /api/v1/scent/orders returns your own assigned fulfilment groups — the shipment(s) assigned to you specifically. There is no separate “accept” call: Linra staff records the assignment on their side (with a window to accept and a further window to ship, both configurable), and you just start working the group. See Orders & fulfilment status for the full read shape, delta sync (changedSince), and status filtering.

Advancing fulfilment status

PATCH /api/v1/scent/orders/{groupId}/status accepts exactly one of the three vendor-reachable targets below — forward-only, and always a clean no-op (never an error) on a backward, stale, or out-of-table target:

You push	Valid from	Requires
Shipped	Pending or Packed	carrier + trackingRef
Delivered	Pending, Packed, or Shipped	carrier + trackingRef if not already recorded
Cancelled	Pending or Shipped	—

Packed is set by Linra staff confirming physical packing — you can never push it yourself, though it may already be the group’s state by the time you push Shipped. See Orders & fulfilment status for the exact request/response shapes and error codes.

FulfillmentStatus — every value

Value	Meaning
PendingSourcing	The order’s line(s) haven’t been assigned a supply option yet (manual sourcing still in progress on Linra’s side) — resolves to Pending once sourcing completes, or to Cancelled if the order is cancelled while still parked. You cannot push against a group in this state; it isn’t assigned to you yet in any actionable sense.
Pending	Assigned to you, not yet packed. Your starting point.
Packed	Marked packed by Linra staff. Never a vendor-pushable target.
Shipped	You’ve pushed Shipped with carrier/trackingRef recorded.
Delivered	Delivered — terminal for a successful shipment, unless it’s later returned.
Cancelled	The group (or the whole order) was cancelled — by you, by the partner, or by Linra staff. Terminal.
Returned	The group’s line(s) completed a return after delivery. You may see this on a group you already marked Delivered; it is driven entirely by the return lifecycle below, never something you push directly.

Your role in a return

A return only reaches you at all when it’s shipped directly back to you (model A) — a return routed through a Linra sorting point never appears on this API. Every action is scoped to your own returns; anything else 404s, indistinguishable from a nonexistent id.

1. PATCH /api/v1/scent/returns/{id}/received — confirm receipt (InTransit → Received).
2. PATCH /api/v1/scent/returns/{id}/inspection/start — start your own inspection (Received → UnderInspection).
3. POST /api/v1/scent/returns/{id}/evidence — upload at least one Photo (a URL, no file-upload endpoint) before your proposal is accepted.
4. PATCH /api/v1/scent/returns/{id}/inspection/propose — record your proposed outcome.

You propose; Linra decides. Your proposed outcome never transitions the request’s status and never moves money on its own — only Linra staff’s own decision (or the silence-timeout worker, if nobody decides in time) is decisive. If you propose Rejected, the request is simply flagged for staff review. See Returns for the full request/response shapes.

ReturnRequestStatus — every value

You see the FULL internal RMA lifecycle, not a collapsed subset, because you participate directly in the physical handling:

Value	Meaning
Pending	The partner has requested a return; awaiting internal review. Moves no money. Not yet visible to you as an actionable item.
Approved	Linra staff authorized the return process to proceed. Moves no money yet.
Declined	Linra staff declined the request outright. Terminal. Moves no money.
WaybillIssued	Linra issued the return waybill / scheduled collection. Moves no money.
InTransit	The item is in transit back to its destination — the point from which you can confirm receipt.
Received	You’ve confirmed receipt (PATCH .../received).
UnderInspection	You’ve started inspection (PATCH .../inspection/start) — you may now upload evidence and propose an outcome.
InspectionAccepted	Linra’s DECISIVE acceptance (defect or sound item) — this is what actually triggers the refund/commission-reversal chain. Terminal.
InspectionRejected	Linra rejects the return (e.g. item was opened/used, no defect found). Terminal. Moves no money.
RefundReleased	The return’s money movements have been recorded on Linra’s side. Terminal.
Withdrawn	The partner withdrew the request themselves before any staff action. Terminal. Moves no money.

Proposed/decided inspection outcome — every value

The same three-value enum is used both for YOUR proposal (supplierProposedOutcome, never authoritative) and Linra’s decision (outcome, decisive):

Value	Meaning
AcceptedDefect	A genuine defect/damage/quality issue. Linra bears the cost; the original shipping fee (if one was charged) is refunded to the partner.
AcceptedSound	The item is sound, no defect (e.g. a changed-mind return). The partner bears the cost; the shipping fee is never refunded.
Rejected	Linra rejects the return (e.g. opened/used, no defect found). Terminal; moves no money. Never reachable via the silence-timeout worker — silence only ever resolves TOWARD AcceptedDefect, never Rejected.

Evidence kind — every value

Value	Meaning
Photo	A damage/condition photo. At least one Photo is required before inspection/propose will accept your proposal.
Document	A supporting document (e.g. a carrier claim form). Display/audit only — never satisfies the Photo requirement on its own.

Carrier — every value

Required alongside a Shipped push (fulfilment) — the same fixed set applies wherever a carrier is recorded on this API:

Value	Meaning
Aramex
SaudiPost
Smsa
Other	Requires the free-text carrierNameOther field alongside it.

Silence has consequences

If a return sits UnderInspection with no decision from either you or Linra staff for the configured window, it is automatically accepted as a defect — a decision that still moves real money (the refund/commission-reversal chain fires exactly as it would for an explicit Linra decision). There’s no upside to leaving a request undecided: confirm receipt, start inspection, and upload evidence promptly.

What you never see

Across every endpoint on this page: the reselling partner’s identity, the order’s own money/tax fields (total, commission, VAT, discount), every internal-staff identity, and every cost-attribution/custody fact behind a Linra decision. You’re paid via your own commercial terms with Linra (offers/cost), never derived from what the partner paid — see Orders & fulfilment status and Returns for the exact field-by-field cut.

Where to go next

• Orders & fulfilment status — full request/response shapes, delta sync, no-op semantics.
• Returns — full request/response shapes for the return door.
• Shipping documents & your dues — what you owe/are owed around a shipment.
• Scent (product overview) — every Scent state catalogue in one compact table.