Orders & fulfilment status

What you can see

GET /api/v1/scent/orders (requires Orders) returns your own assigned fulfilment groups — never a sibling vendor’s group, never Linra’s own (Self-fulfilled) group, and never another vendor’s lines on a multi-vendor order. Every field is chosen against a strict test: “does a vendor need this to physically pack and ship the shipment?” That excludes, permanently:

• The reselling partner’s identity.
• The partner’s own customer/external reference.
• Every money and tax field — order total, commission, VAT breakdown, currency, discount code and amount, tax-registration numbers. You are paid via your own commercial terms with Linra (tracked entirely on the offer/cost side), never derived from what the end partner paid.
• The internal saga/orchestration correlation id.

What you DO get: the group id (groupId — your own correlation reference for this shipment), fulfilment status, your own previously-pushed vendor order id, a grouped shipTo (recipient/address) and tracking (ref/carrier/carrierNameOther) object, and each line’s variant id / SKU / quantity.

Accepting an assignment

There is no “accept” call on this API today. When a group is first assigned to you, Linra staff give you a fixed window to accept and a further window to ship it (both configurable; a typical default is 24 hours each) — but accepting it, right now, is a Linra-side action recorded by staff, not something you push through this API. Just start working the group (see “Pushing fulfilment status” below) — there’s nothing else to call first.

Status values you’ll see

A group’s status can be any of the following — not only the five values you can push TOWARD (see “Pushing fulfilment status” below):

Status	Meaning
PendingSourcing	The order’s line(s) haven’t been assigned a supply option yet (manual sourcing still in progress) — a park-at-create state that resolves to Pending once sourcing completes, or to Cancelled if the order is cancelled while still parked.
Pending	Assigned to you, not yet packed.
Packed	Marked packed by Linra staff (you can never push this yourself — see below).
Shipped	You’ve pushed a Shipped status with carrier/trackingRef.
Delivered	Delivered — terminal for a successful shipment.
Cancelled	The group (or the whole order) was cancelled.
Returned	The group’s line(s) completed a return after delivery — you may see this on a group you already marked Delivered; it’s driven by the partner’s own return-request lifecycle, not something you push.

Filtering by status

status is a repeatable, match-any query parameter (?status=Shipped&status=Delivered) — a single occurrence works too. Omit it entirely to receive every status.

Delta sync

Pass changedSince (an ISO-8601 UTC instant) to receive only groups whose parent order changed strictly after that time, ordered by change time ascending instead of the default newest-first order. Use the timestamp of the LAST item you successfully processed as the next poll’s changedSince — the same pattern used for catalog delta sync on the partner side. Combine freely with the status filter above.

One deliberate over-inclusion to be aware of: because the underlying signal is the parent order’s own timestamp (a fulfilment group itself carries no timestamp of its own), a SIBLING vendor’s group changing on the same multi-vendor order also bumps this value — you may occasionally see your own, genuinely-unchanged group again on the next poll. Treat this as safe and over-inclusive, never under-inclusive, and reconcile the same way you already handle a repeated, identical status (a no-op).

Pushing fulfilment status

PATCH /api/v1/scent/orders/{groupId}/status (requires Orders) accepts exactly one of:

Target status	Valid from	Effect
Shipped	Pending or Packed	Sets shippedAt (if not already set); stores trackingRef and carrier.
Delivered	Pending, Packed, or Shipped	Sets deliveredAt. shippedAt is backfilled to the same moment if it isn’t already set — e.g. a direct Pending/Packed → Delivered jump that skips a Shipped push of its own.
Cancelled	Pending or Shipped	Cancels the group.

carrier and trackingRef are REQUIRED on a Shipped push (one of Aramex, SaudiPost, Smsa, or Other — carrierNameOther is additionally required when carrier is Other). Unlike an invalid/backward target (a graceful no-op — see below), a Shipped push missing either field is a hard rejection: 400 VALIDATION_ERRORS when carrier itself is missing, or 422 BUSINESS_SHIPMENT_MISSING_TRACKING when a carrier is present but no tracking number is available yet (from this call or, if the group was already Packed with its carrier already recorded, from that earlier state). A Delivered push that jumps straight from Pending/Packed (skipping your own Shipped push) is held to the SAME requirement internally — you must still supply carrier + trackingRef on that call, since Linra’s own tracking record has to pass through the same in-transit state on its way to Delivered.

You can never PUSH Packed yourself — it’s an internal operator-only transition, set by Linra operations confirming packing before shipment. It CAN, however, already be the group’s current status by the time you push Shipped/Delivered (the operator packed first, then you shipped) — the table above reflects that. Pushing Packed as your OWN target (or any value outside the table) is rejected the same way an invalid transition is (see below), never a distinct error.

No-ops, not errors

A push that can’t apply — a backward transition, an already-applied identical status, or an out-of-table target like Packed — returns a normal 200:

{
  "state": "SUCCESS",
  "payload": {
    "applied": false,
    "group": { "groupId": "...", "status": "Shipped", "...": "..." }
  }
}

applied: false means the group’s state is UNCHANGED by this call — the group field always reflects the group’s real current state either way, so your automation can distinguish “my push took effect” from “the group was already past that point” without treating the latter as a failure worth alerting on. This makes status pushes safe to retry blindly and safe to re-send on every status-change event your own system generates, even out of order.

Scoping

A groupId belonging to another vendor is reported as 404 NOT_FOUND_FULFILLMENT_GROUP on both the read and the status-push endpoint — indistinguishable from a nonexistent id.