# Public Orders Create

Create an order from uploaded files (async processing).
The programmatic twin of forwarding a purchase-order email: Mercura
stores the files, extracts the order metadata (customer, references,
delivery), matches the line items against your catalogue, and lands the
order ready for review / ERP export.
**Response.**
- `202 Accepted` with `JobAck { job_id, status_url }` on the first
call.
- `200 OK` with the *same* `JobAck` on an idempotent replay (same
`Idempotency-Key` + same form fields and file contents).

**What to do next.** Poll `GET /jobs/{job_id}` until `status` is
`COMPLETED` or `FAILED`, or subscribe to the
`request.processing_completed` webhook and correlate by `job_id`.
The order is then readable via `GET /orders`.
**Idempotency.** Pass an `Idempotency-Key` header (≤ 255 chars). Same
key with a *different* body returns `422 IDEMPOTENCY_KEY_MISMATCH`.

Endpoint: POST /orders
Version: 1.33.0

## Header parameters:

  - `authorization` (string | null)
    Bearer <mrc_live_…> API key

  - `Idempotency-Key` (string | null)
    Optional client-supplied key for safe retries; <= 255 chars

## Request fields (multipart/form-data):

  - `files` (array, required)
    One or more files, exactly as you would attach them to a forwarded email: GAEB, .xlsx, .csv, .docx, .txt, .pdf, images (.png/.jpg/.jpeg/.gif/.bmp/.tiff/.webp), and .eml. Max 50 MB per file, 100 MB total, 20 files.

  - `name` (string | null)
    Display name for the order in Mercura (the email channel uses the subject line). Defaults to the primary file's name.

  - `customer_id` (string | null)
    Your customer id — the same identifier the customers resource exposes as `customer_id`. Takes precedence over customer_email. An unknown id is not an error — the order is created without a customer, exactly like an email from an unknown sender.

  - `customer_email` (string | null)
    Customer contact email, matched with the same rules the email channel applies to the sender address (exact contact match, domain pattern, unique inferred domain).

  - `context` (string | null)
    Free-text context that helps Mercura process the order — e.g. the original email body, delivery notes, or guidance for article matching.

## Response 200 fields (application/json):

  - `job_id` (string, required)

  - `status_url` (string, required)
    Relative URL to poll for this job's status