Skip to content
/
Public Orders Get

Public Orders Get

Request

Fetch one order by its public id.

Path
order_idstring(Order Id)required
Headers
authorizationstring or null(Authorization)

Bearer <mrc_live_…> API key

curl -i -X GET \
  'https://docs.mercura.ai/_mock/openapi/orders/{order_id}' \
  -H 'authorization: string'

Responses

Successful Response

Bodyapplication/json
idstring(Id)required

Public id; equals request_id for an order.

Example:"20456"
request_idstring(Request Id)required

Mercura request id backing this order.

Example:"20456"
statusstring(PublicOrderStatus)required

Lifecycle state of an order (open enum — new values are SemVer MINOR).

A translated subset of the internal OrderWorkflowStatus (see README → Design decisions → Public offer status as a translated subset). The internal INCOMPLETE_METADATA is folded into NEEDS_REVIEW — both mean "a human still has to act" — so the public surface exposes a single action-required state. The mapping lives in services.orders_service._ORDER_STATUS_MAP and a test asserts it covers every internal value, so a new internal state is a loud failure rather than a silent passthrough.

Enum:"PROCESSING""NEEDS_REVIEW""READY_TO_EXPORT""EXPORTED""ARCHIVED"
Example:"READY_TO_EXPORT"
completed_atstring or null, (date-time)(Completed At)

When the order was last completed (finalised / exported). Refreshed on every completion; null if never completed. Use it with the GET /orders?completed_since=… completion feed.

customerobject(PublicOfferCustomer)

Customer the offer was made to. Sourced from Request.customer_bp.

On the wire the customer's partner-id is named customer_id — the same field name the customers resource uses, so a partner ingesting an offer can resolve the reference via GET /customers/{customer_id}.

The Python attribute is still external_id to keep the shared projection (features/customer_offers/offer_projection.py) indifferent to the rename. serialize_by_alias=True plus the field's serialization_alias make every JSON path (FastAPI response, model_dump(mode='json') in the webhook emitter) emit customer_id.

Example:
{
  "address": {
    "city": "Düsseldorf",
    "country": "DE",
    "postal_code": "40210",
    "street": "Industriestraße",
    "street_number": "12"
  },
  "contact_person": "Thomas Weber",
  "custom_fields": {
    "Kundengruppe": "Elektrogroßhandel"
  },
  "customer_id": "K-10042",
  "name": "Elektro Mustermann GmbH"
}
projectobject(PublicOfferProject)

Project / object the offer relates to. Sourced from Request.project.

Example:
{
  "name": "Neubau Bürogebäude Rheinpark",
  "object_number": "OBJ-2026-0042"
}
request_custom_fieldsobject or null(Request Custom Fields)

Organisation-defined custom fields on the underlying request, keyed by the field's display label. Null when the request carries none.

Example:
{
  "Angebots-Nr": "AN-2026-0042"
}
positionsArray of objects(Positions)
Example:
[
  {
    "article_number": "LEU-1500-50-840",
    "description": "LED-Feuchtraumleuchte 1500 mm 50 W 4000 K IP65",
    "is_alternative": false,
    "position_number": "10",
    "quantity": 48,
    "unit": "Stk"
  },
  {
    "article_number": "LEU-1200-30-840",
    "description": "LED-Feuchtraumleuchte 1200 mm 30 W 4000 K IP65",
    "is_alternative": false,
    "position_number": "20",
    "quantity": 24,
    "unit": "Stk"
  }
]
totalsobject(PublicOfferTotals)required

Aggregate amounts for the offer, all in EUR.

Mirrors pdf_offer_service._build_real_data: positions_subtotal is the sum of line_net across non-alternative positions; net_total prefers Request.net_total if set (header-level discount applied), otherwise equals positions_subtotal; gross_total prefers Request.gross_total if set, otherwise is the sum of line_gross across non-alternative positions.

Example:
{
  "gross_total": "0.00",
  "net_total": "0.00",
  "positions_subtotal": "0.00"
}
order_metadataobject(PublicOrderMetadata)

Extracted order-level metadata. Null while the order is still parsing.

Example:
{
  "contact_person": "Thomas Weber",
  "customer_reference": "PO-88213",
  "delivery_address": {
    "city": "Düsseldorf",
    "country": "DE",
    "postal_code": "40213",
    "street": "Rheinuferstraße",
    "street_number": "45"
  },
  "delivery_recipient": "Baustelle Rheinpark",
  "order_date": "2026-07-08",
  "project_number": "OBJ-2026-0042",
  "quote_number": "AN-2026-0042",
  "requested_delivery_date": "2026-07-22",
  "shipping_terms": "frei Baustelle",
  "special_instructions": "Anlieferung nur vormittags 7–12 Uhr."
}
erp_offer_idstring or null(Erp Offer Id)

The partner-side ERP order id, when known — from your acknowledgement's external_id or a previous Mercura-managed export; otherwise null.

Example:"SO-2026-5567"
acknowledgementobject(PublicOrderAcknowledgement)

Your last reported ERP import outcome for this order, or null if none yet.

Example:
{
  "acknowledged_at": "2026-07-08T09:06:00Z",
  "external_id": "SO-2026-5567",
  "message": "Bestellung als Kundenauftrag angelegt.",
  "metadata": {
    "sales_order": "SO-2026-5567"
  },
  "status": "SUCCESS"
}
created_atstring, (date-time)(Created At)required
Example:"2026-07-08T08:30:00Z"
updated_atstring, (date-time)(Updated At)required
Example:"2026-07-08T09:05:00Z"
Response
{
  "created_at": "2026-07-08T08:30:00Z",
  "customer": {
    "address": { … },
    "contact_person": "Thomas Weber",
    "custom_fields": { … },
    "customer_id": "K-10042",
    "name": "Elektro Mustermann GmbH"
  },
  "erp_offer_id": "SO-2026-5567",
  "id": "20456",
  "order_metadata": {
    "contact_person": "Thomas Weber",
    "customer_reference": "PO-88213",
    "delivery_address": { … },
    "delivery_recipient": "Baustelle Rheinpark",
    "order_date": "2026-07-08",
    "project_number": "OBJ-2026-0042",
    "quote_number": "AN-2026-0042",
    "requested_delivery_date": "2026-07-22",
    "shipping_terms": "frei Baustelle",
    "special_instructions": "Anlieferung nur vormittags 7–12 Uhr."
  },
  "positions": [
    { … },
    { … }
  ],
  "project": {
    "name": "Neubau Bürogebäude Rheinpark",
    "object_number": "OBJ-2026-0042"
  },
  "request_custom_fields": {
    "Angebots-Nr": "AN-2026-0042"
  },
  "request_id": "20456",
  "status": "READY_TO_EXPORT",
  "totals": {
    "gross_total": "0.00",
    "net_total": "0.00",
    "positions_subtotal": "0.00"
  },
  "updated_at": "2026-07-08T09:05:00Z"
}