Document Loop and Queue

The document loop starts with an approved cXML OrderRequest. Magento can record, validate or create an order from that request. When fulfilment begins, Magento can send a ConfirmationRequest, ShipNoticeRequest and InvoiceDetailRequest to the procurement system.

Order creation and returned-cart pricing are covered in Inbound Orders and Pricing. This page focuses on outbound documents and their queue.

Configure outbound cXML identity

Generated cXML uses the effective supplier credential domain, identity and shared secret retained for the inbound order. Configure those values before enabling ConfirmationRequest delivery or testing shipment and invoice callbacks. Buyer-profile settings override Store-view defaults.

Configure a separate endpoint for each document type: Confirmation URL, ASN URL and Invoice URL. The browser cart-return URL is used only to return the shopping cart and is never reused for later server-to-server documents.

Magento generates cXML 1.2.070 envelopes for confirmation, shipment and invoice documents. The destination must be a validated HTTPS URL.

ConfirmationRequest

When Send cXML ConfirmationRequest is enabled, the effective Confirmation Mode decides how the document is prepared.

• Automatic Whole-Order Confirmation confirms a successfully created order without waiting for an administrator. A cancellation produces the corresponding rejection.
• Manual Line Confirmation waits for an administrator to decide every order line in Punchout > Inbound Orders.

For a manual confirmation, open the inbound order and select Accept, Reject or Backordered for every line. Accepted and backordered lines may include an expected delivery date. Rejected lines cannot have a delivery date. Every inbound line must have exactly one decision before the confirmation can be submitted.

Submitting the form creates one immutable confirmation document in the queue. The same inbound order cannot create a second confirmation. Its expected-delivery values are shown in the Admin user's locale, while the cXML document uses the protocol's ISO date format.

A delivery failure remains visible with the inbound order and queue entry so an administrator can diagnose the receiver before retrying.

Automatic outbound documents

When Magento saves a shipment or invoice, the module checks whether its order quote is linked to a PunchOut context.

• A shipment creates one asn_outbound queue row containing the shipment number, tracking information and shipped SKU quantities.
• An invoice creates one invoice_outbound queue row containing the invoice number, order references, item details, summary amounts and order currency.
• The same Magento entity is not queued twice for the same document type.

The queue builds the outbound document once, encrypts the exact payload at rest and sends it to the document-specific HTTPS endpoint. Retries reuse the same retained payload and routing data. Shipment and invoice delivery therefore remains independent of the short-lived browser context.

Queue processing

Each queue detail keeps the business entity, buyer, attempt count, safe request summary and delivery result together. The examples below show the three outbound document types from one completed order lifecycle; each receiver returned HTTP 204.

The punchout_document_queue_process job runs in Magento's default cron group every five minutes. It processes due pending rows per store, using the store-scoped batch size and retry settings.

For queue inspection and controlled document-type processing, see Operations and CLI.

Statuses are:

• pending: ready now or waiting until next_attempt_at;
• processing: claimed by a worker or Force Run;
• completed: the document endpoint answered successfully;
• failed: the maximum attempts were used.
• delivery_unknown: Magento cannot determine whether the remote system received the document, so automatic retry is stopped to avoid a duplicate business document.

Network exceptions and non-2xx responses count as failures. A row below its maximum returns to pending with the configured delay.

An interrupted delivery can produce delivery_unknown when the remote outcome is ambiguous. Review the receiving system first. Only an administrator with the dedicated permission can deliberately schedule that row again.

Confirmation delivery is durable. When the effective configuration requires a confirmation, the inbound-order record retains the immutable supplier routing and the queue can recover a missing confirmation intent after a worker or deployment interruption. The synchronous OrderRequest response does not wait for a remote confirmation endpoint. This keeps order acknowledgement separate from later server-to-server document delivery while still leaving the intent visible in Document Queue.

Work with a failed row

Open Punchout > Document Queue, then View the row.

• Force Run schedules the row immediately and processes it once. It does not erase the existing attempt count.
• Reset clears attempts, response and error data and returns the row to pending. Use it only after the underlying configuration or receiver problem has been corrected.
• Retry Unknown Delivery deliberately reschedules a delivery_unknown row after the receiving system has been checked.
• Delete removes the operational record and should not be used as a substitute for diagnosing delivery.

The module and queue must be enabled for the row's Store view, the retained supplier identity must be complete, and the document-specific URL must accept HTTPS POST requests. Read the saved HTTP response or transport error before resetting the attempt count.

Direct document endpoints

/punchout/document_asn/outbound and /punchout/document_invoice/outbound execute the same document delivery handlers immediately and return their result. They use the effective document-specific endpoint and do not create a Magento shipment or invoice.

Send a client-generated X-Punchout-Request-Key for OrderRequest, ASN and invoice calls. Reuse it only for the same semantic request. Magento replays the saved result for an exact retry and rejects changed input that reuses the key.