Skip to content
/
Reading orders

Reading orders

GET /orders and GET /orders/{order_id} return an order's matched line items plus order-specific metadata. Keyed by the request id — an order has a single result, so order_id == request_id. (Note: unlike a tender — which is now a nested chapters[] tree with id-only customer_id / project_id — an order returns a flat positions[] list and full customer / project objects.)

  • status — the order's workflow state: PROCESSING, NEEDS_REVIEW (metadata or line matches need a human), READY_TO_EXPORT, EXPORT_FAILED (an export attempt was rejected and a human is reworking the order), EXPORTED, ARCHIVED.
  • completed_at — when the order was last completed (finalised / exported), or null if it never was. Refreshed on every completion; drives the completion feed below.
  • customer — the party that placed the order: the resolved business partner (customer_id, name, address, contact person). recipient — the goods recipient (Warenempfänger) in the same shape, when Mercura resolved one against your customer master; null otherwise. project — object_number and name.
  • positions[] — one entry per line item. Each carries position_number, article_number (the catalogue match, when the line was matched), description, quantity, and unit. A line the agent could not match still appears, with its verbatim number / description and a null article_number. delivery_schedule[] contains the line's ordered quantity/date allocations (quantity, unit, requested_delivery_date) when the customer requested split deliveries; ordinary lines return an empty list. These line dates do not replace the order-header order_metadata.requested_delivery_date.
  • order_metadata — the extracted order header: customer_reference (the customer's PO number), order_date, quote_number, project_number, requested_delivery_date, shipping_terms, contact_person, special_instructions, and the delivery_recipient / delivery_address (Warenempfänger) when different from the customer. Null while the order is still parsing.
  • erp_offer_id — the partner-side ERP order id when known (populated from a SUCCESS acknowledgement's external_id, or from a Mercura-managed ERP export).
  • acknowledgement — your last reported import outcome for this order (status, external_id, message, metadata, acknowledged_at), or null until you acknowledge it (see below).

Two parties per order. customer is the party that placed the order, recipient the party the goods go to — two separate blocks so an ERP that distinguishes them (SAP's sold-to and ship-to, for instance) can map one to each. Both are customer references: resolve either customer_id via GET /customers/{customer_id}. When the order ships to the account that placed it, both blocks carry the same customer_id. recipient is null when no recipient partner could be resolved; the document's own delivery name and address then remain under order_metadata.delivery_recipient / delivery_address, which are free text and carry no account number.

Prices. Orders are a matching, not a pricing, workflow. Line items carry the matched article, quantity, and unit but no prices, so list_price / net_price / line_net / line_gross are null and totals are 0. The positions and order_metadata are the payload that matters. (The totals block is kept for shape-parity with tenders.)

Use modified_since on GET /orders for delta-sync catch-up scans.