Skip to content

Order management

Find orders that changed, read their current state, and accept, reject, cancel or ship them.

Handling orders is a polling loop: find orders that changed, read each order's current state, and act on it for the seller. You need an access token from the authorization_code flow with scope v2 read write (see Authentication in the API reference) and the Version: 2.0 header on every request.

Endpoint details are in the API reference: Order and Status. The order change feed works like the advert change feed described in Advert and order status synchronization.

  1. Discover what changed — GET /api/partner/status/orders.

    • Always send since (ISO-8601 instant with timezone). Optionally cursor (from your previous response's nextCursor) and limit.
    • Response: data (changed order UUIDs, oldest first), hasMore, nextCursor.
    • Persist nextCursor after every poll, even on an empty page, and send it back as cursor on the next call. This is your resume point.
    • A change is visible only a few seconds after it happened — don't assume same-second consistency.
    • This feed returns identifiers only; it never carries order content.
  2. Fetch the order's current state — GET /api/partner/orders/{orderId}, for each ID surfaced in step 1 (or on your own polling cadence for orders you already track).

    • Returns status, block_reason, items, cost, shipment, buyer_invoice.
    • This single status field is the seller-facing projection of several independent OLX sub-systems (confirmation, delivery/dispatch, payout, KYC, tax compliance). Field-level detail is in the Order reference.
  3. Branch on status:

    • PENDING_CONFIRMATION (has expires_at) → seller must accept or reject before the deadline:
      • Optionally GET /api/partner/orders/{orderId}/accept-requirements first to see what's still missing (payout_method, payout_details, sender_details, terms_accepted, etc.) before attempting acceptance — avoids a wasted 422.
      • Optionally GET /api/partner/orders/{orderId}/posting-windows if you want to offer the seller a pickup-time choice to submit as sender_details.posting_window on accept.
      • POST /api/partner/orders/{orderId}/accept — optionally submits payout method/details, sender details, and terms acceptance in the same call. Returns 204 on success, or 422 with required_actions if preconditions are still unmet.
      • POST /api/partner/orders/{orderId}/reject — terminal; requires a reason (see the Order reference for the enum). Use this instead of cancel for anything not yet accepted.
    • AWAITING_SHIPMENT and shipment.label_available: true → GET /api/partner/orders/{orderId}/label to download the shipping-label PDF and hand the parcel to the carrier.
    • PAYOUT_BLOCKED with a block_reason → surface the reason to the seller (IDENTITY_VERIFICATION_REQUIRED / _IN_PROGRESS / _FAILED, or TAX_COMPLIANCE_REQUIRED) and poll again later; there is no partner API call that resolves this — the seller resolves it through the OLX consumer-facing verification flow.
    • Any state where the seller can no longer fulfill (out of town, item already sold elsewhere, etc.) and the order was already accepted → POST /api/partner/orders/{orderId}/cancel with a reason. Cancellation of an order still AWAITING_SHIPMENT may be asynchronous — re-poll order details to observe the resulting state.
    • PENDING_CONFIRMATION orders cannot be cancelled — cancel on such an order returns 422 ORDER_NOT_CANCELLABLE with a hint to use reject instead.
  4. Loop. Keep polling the status feed on a schedule with your saved cursor; re-fetch order details whenever an ID reappears.