The retailer's PO identity is externalId within the channel: a transaction advisory lock on it is taken before the lookup, so concurrent deliveries resolve to one purchase order. onDuplicate update (the default) changes the fields sent and answers unchanged when nothing differs; skip answers the stored PO; error is 409 duplicate. Lines resolve their product by id, externalId in the channel, sku, barcode; a line whose product does not resolve is kept unmapped with a warning (accept refuses until it is mapped). Totals are recomputed: a mismatch is 422 totals_mismatch with the computed values.

Scope: purchase-orders:write, channel:write or admin.

Idempotency: send Idempotency-Key; a retry with the same key replays the first answer.

Rate limit: write class, 1,200 requests per minute per tenant by default (read class 6,000). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a refusal is 429 rate_limited with Retry-After.