Orders & fulfilment status

What you can see

GET /api/v1/vendor/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, Linra’s own canonical order id (for support correlation — never the partner’s own reference), fulfilment status, your own previously-pushed vendor order id and tracking reference, the shipping destination, and each line’s variant id / SKU / quantity.

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.

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/vendor/orders/{groupId}/status (requires Orders) accepts exactly one of:

Target status	Valid from	Effect
Shipped	Pending or Packed	Sets shippedAt (if not already set); optional trackingRef is stored.
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.

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.