Confirm receipt of your own returned item

PATCH

/api/v1/scent/returns/{id}/received

curl --request PATCH \
  --url https://api-omni-vendors.linra.net/api/v1/scent/returns/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/received \
  --header 'Authorization: Bearer <token>'

• Production (W-01/W-02 — the vendor Gateway's own dedicated domain, separate from the partner Gateway; not yet deployed to this host, see the Getting started guide)
• Staging (W-01/W-02 — not yet deployed to this host)
• Local development (vendor Gateway default port)

Model-A supplier door: InTransit -> Received. Reaches ONLY a return request whose destination is your own vendor id (ReturnDestinationType == Supplier) — any other request 404s. Rejects a request not currently InTransit with BUSINESS_RETURN_REQUEST_INVALID_TRANSITION. Requires the Orders capability.

Authorizations

• vendorBearer

Parameters

Path Parameters

id

required

string format: uuid

The return request id.

Responses

200

The return request, vendor-safe.

Media typeapplication/json

object

state

required

string

payload

required

details

object

payload

required

Deliberately EXCLUDES the reselling partner’s identity (PartnerId — Linra’s B2B2B relationship, not yours), every internal-staff identity, and every cost-attribution/custody/ carrier-claim fact — the same “does a vendor need this” test VendorFulfillmentGroupResponse applies.

object

id

string format: uuid

orderGlobalId

Linra’s own canonical order id — stable support-correlation reference.

string

returnRequestNumber

string

nullable

status

string

requestedAt

string format: date-time

receivedAt

string format: date-time

nullable

inspectionStartedAt

string format: date-time

nullable

inspectionDecidedAt

string format: date-time

nullable

inspection

object

receivedAt

string format: date-time

nullable

receivingParty

Always Supplier for a row reachable on this API at all.

string

Allowed values: Supplier

inspectionStartedAt

string format: date-time

nullable

inspectionWindowDeadline

string format: date-time

nullable

outcome

Linra’s DECISIVE outcome, once decided (null until staff — or the silence-timeout worker — decides). Never writable by you.

string

Allowed values: AcceptedDefect AcceptedSound Rejected

supplierProposedOutcome

Your own proposed outcome, echoed back.

string

Allowed values: AcceptedDefect AcceptedSound Rejected

requiresStaffReview

boolean

evidence

Array<object>

object

id

string format: uuid

url

string format: uri

kind

string

Allowed values: Photo Document

uploadedAt

string format: date-time

lines

Array<object>

object

scentOrderLineId

string format: uuid

quantity

integer

reasonCode

string

Example

{
  "state": "SUCCESS",
  "payload": {
    "status": "Received",
    "inspection": {
      "receivingParty": "Supplier",
      "outcome": "AcceptedDefect",
      "supplierProposedOutcome": "AcceptedDefect",
      "evidence": [
        {
          "kind": "Photo"
        }
      ]
    }
  }
}

403

Your token doesn’t carry the capability this endpoint requires.

Media typeapplication/json

object

state

required

string

payload

details

object

Examples

ExamplemissingCapability

{
  "state": "FORBIDDEN_CAPABILITY_NOT_GRANTED",
  "payload": null,
  "details": {
    "requiredCapability": "Orders"
  }
}

404

Unknown return request id, one belonging to another vendor, or one not destined to a supplier at all (a Linra-sorting-point-bound return — never reachable on this API).

Media typeapplication/json

object

state

required

string

payload

details

object

Examples

ExamplenotFound

{
  "state": "NOT_FOUND_RETURN_REQUEST",
  "payload": null,
  "details": {}
}

422

The request is not currently InTransit.

Media typeapplication/json

object

state

required

string

payload

details

object

Examples

ExampleinvalidTransition

{
  "state": "BUSINESS_RETURN_REQUEST_INVALID_TRANSITION",
  "payload": null,
  "details": {}
}

429

Too many requests. Retry after the Retry-After header (seconds).

Media typeapplication/json

object

state

required

string

payload

details

object

Example

{
  "state": "NOT_FOUND_VENDOR_OFFER"
}

Headers

Retry-After

integer

Seconds to wait before retrying.