POST /v1/orders — submit an order in Italy
Idempotent order submission with X-Idempotency-Key. Returns 201 with order_id, or 409 on duplicate. IVA 22% computed server-side.
Request schema
POST /v1/orders with JSON body: { idempotency_key, buyer:{vat_id, billing_address}, ship_to:{name, address (must include Milano postal code format), contact}, lines:[{sku, qty, unit_price_cents, currency:'EUR'}], promised_date, po_number, tax_mode:'incl_iva' }. VAT ID validated against VIES (EU) in real time. Max 250 lines per order; split larger orders or use bulk import.
Response & status flow
201 Created → { order_id, status:'accepted', estimated_iva_amount_cents, currency, fulfilment_hub:'Milano', invoice_channel:'SdI' }. State transitions emitted as webhook events: accepted → confirmed → in_production → shipped → delivered. Each transition writes an entry to GET /v1/orders/{id}/events.
Validation errors
400 with RFC 7807 problem+json: invalid_vat (VIES mismatch), invalid_sku (not in country catalog), min_qty_violation (below MOQ for the SKU), invalid_iva_rate (mismatch with 22%), idempotency_conflict (same key, different body). All errors include human-readable detail and a stable type URI.
FAQ
Is the endpoint idempotent?
Yes — pass X-Idempotency-Key (UUID v4 recommended). Same key + same body returns the existing order; same key + different body returns 409 conflict.
What currencies are accepted?
EUR for Italy (PLN also for Poland). Unit prices in minor units (cents/grosze). Mixed-currency lines rejected with 400 invalid_currency_mix.
What about partial fulfilment?
Default off. Set partial_ok:true in the request to allow split shipments. Each shipment gets a separate invoice via SdI.
How are taxes computed?
Server-side based on buyer VAT status, ship-to country and SKU tax class. IVA 22% applied to Italy domestic; reverse-charge for valid EU B2B (VIES OK). Returned as estimated_iva_amount_cents.
Can I cancel an order via the API?
DELETE /v1/orders/{id} allowed in accepted and confirmed states. After in_production we coordinate by email — call our AE.