Submit an order. Get an answer your system can act on.

Authenticate

Send your key in the X-API-Key header. Keys are scoped by default to orders, review, upload and reads; an admin can issue full-access keys from Settings. Every tenant-scoped path starts with /api/v1/tenants/{tenantId}. Signed-in users of the web app find their tenant id and can mint a key on the in-app developers page.

curl https://api.example.com/api/v1/tenants/{tenantId}/orders \
  -H "X-API-Key: YOUR_KEY"

Submit

POST /api/v1/tenants/{tenantId}/orders with a base64 document or structured lines; the response carries an envelopeId. Supported formats: PDF, CSV, XLSX, DOCX, HTML, TXT, EML, or images (PNG, JPG, GIF, WEBP). An unsupported file is refused with HTTP 415 before anything is read. Send an Idempotency-Key header so a retried submission is answered with the original envelope instead of a second one. POST /invoices takes a supplier invoice the same way.

POST /api/v1/tenants/{tenantId}/orders
X-API-Key: YOUR_KEY
Idempotency-Key: po-48821-2026-09-23
Content-Type: application/json

{ "channelId": "YOUR_CHANNEL_ID", "document": "<base64 PDF>" }

202 { "envelopeId": "734f823d-..." }

Follow it

GET /api/v1/tenants/{tenantId}/review/{envelopeId}, or the get-envelope-status MCP tool, returns the envelope with its status. Terminal statuses: exported, rejected, failed, manual_handling. in_review means a person has it; stop polling and wait for the webhook. Rate limits are per tenant and per plan: Core 1,000, Growth 2,000, Scale 3,000 requests a minute (Enterprise 3,000). A separate backstop of 1,000 requests a minute applies per client IP before authentication.

Terminal, stop polling

exportedrejectedfailedmanual_handling

A person has it, wait for the webhook

in_review

Be told

Register a URL and a secret with POST /webhooks. Each delivery is a JSON body of { event, timestamp, data, id, attempt }, signed with HMAC-SHA256 over "timestamp.body" and sent with X-OrderFlow-Signature, X-OrderFlow-Timestamp, X-OrderFlow-Event and X-OrderFlow-Delivery-Id headers. The id is stable across retries so you can dedupe. A failed delivery is retried with backoff for about nine hours and then parked for manual redelivery.

The events an ordering agent subscribes to first

• envelope.in_review The order is waiting for a person. Carries the routing decision (adjustedScore, action) and the order summary.
• envelope.auto_approved The order was approved without a person. This is the event you are billed on.
• envelope.approved A person approved the order. Delivery to its destination follows.
• envelope.rejected The order was rejected, by a person or because it fell below the reject threshold.
• envelope.manual_handling The order was parked for manual handling, by a person or because a destination needs one.
• envelope.failed Processing stopped and will not retry. errorCode says why (for example DAILY_BUDGET_EXCEEDED or UNSUPPORTED_DOCUMENT_TYPE).
• envelope.exported The approved record was written or exported. A terminal status.
• envelope.destination.completed One destination landed. Fires per destination when an order goes to more than one system; carries connectorLabel, realmId and externalUrl.
• envelope.duplicate_blocked A document with the same PO reference was already accepted, so this one was held.
• order.acknowledged The buyer was sent an acknowledgement for the order. Carries the acknowledgement your customer system can read.

Use it from an agent

The MCP server exposes 186 tools over stdio, one tenant per process, for Claude Desktop, Claude Code, Cursor or any MCP client. It is a private package (@orderflow/mcp-server) built from a checkout of the repository at packages/mcp-server; the in-app developers page has the exact configuration with your tenant id filled in.

The five tools an ordering agent needs

• submit-order
• submit-orders-bulk
• get-envelope-status
• get-order
• explain-order-routing

Errors

Every error is { error: { code, message, details, correlationId } }. Quote the correlationId to support. These are the codes an ordering agent must handle on purpose:

For retailers and marketplaces (beta target)

If your suppliers use Poppelo, your procurement agent can submit to their tenant with a key they issue, receive the order.acknowledged event with the acknowledgement they send, and read the routing explanation for any order that was held. The supplier hands you one thing: an integration-scoped key. Contact us to join the beta.

Questions from agent developers