View Extension
Back to Knowledge Base
Download PDF
Current page This article as PDF Complete manual All pages in this extension manual

PunchOut Documentation

SoftwareSilo PunchOut connects a Magento 2 catalog to a buyer's procurement system. A buyer starts an OCI or cXML session, shops in Magento with the customer and pricing context resolved by the buyer profile, and sends the finished cart back instead of placing a normal storefront order.

Use this guide if you are integrating Magento Open Source or Adobe Commerce with an OCI or cXML buyer, including projects involving SAP, SAP Ariba, Coupa or Oracle Procurement.

How the workflow fits together

  1. An active buyer profile identifies the procurement account and authenticates its request.
  2. An OCI login or cXML setup request creates a short-lived PunchOut context.
  3. Magento activates the resolved guest or customer session and applies the configured storefront-operation policy.
  4. The buyer builds a cart in Magento or through the tokenized cart endpoints.
  5. Return to System maps the cart and posts it to the buyer's return URL.
  6. After approval, a cXML buyer can send an OrderRequest. Depending on the configured processing mode, Magento records it, validates it or creates a sales order.
  7. Magento can send confirmation, shipment and invoice cXML documents back through the document queue.
The procurement system authenticates through a buyer profile, opens a Magento shopping context, receives the returned cart, and continues its own approval and purchase-order process. Shipment and invoice documents can later use the optional queue.

Terms used in this guide

  • PunchOut — the name of the integration pattern: a buyer "punches out" of their procurement system into the supplier's shop and returns the filled cart for internal approval instead of ordering directly.
  • Procurement system — the buyer-side purchasing software (for example SAP Ariba, Coupa or Oracle Procurement) that opens the PunchOut session and later receives the cart.
  • OCI (Open Catalog Interface) — the simpler, form-based PunchOut protocol; login credentials and the cart-return URL arrive as HTML form fields.
  • cXML (commerce XML) — the richer XML-based PunchOut protocol; authentication, cart return and order documents are XML messages defined by the cXML standard (its structure rules are called the DTD).
  • Buyer profile — the Magento Admin record that identifies one procurement account: credentials, return URLs, mapping rules and operation policy.
  • BuyerCookie — the session cookie a cXML buyer sends back with each request so Magento can continue the PunchOut session.
  • Extrinsic — a named key/value pair inside a cXML request or cart line (for example a buyer's cost center); mapping profiles read extrinsics into Magento fields.
  • Level-2 data — the per-line detail in a returned cart (SKU, quantity, unit price) that procurement systems need for approval; some platforms additionally expect tax and shipping breakdowns.
  • JIT (just-in-time) — provisioning: creating the Magento customer account automatically when a buyer first logs in, instead of pre-creating accounts.
  • Idempotent — safe to retry: processing the same request twice produces the same result once, so a repeated OrderRequest does not create duplicate orders.

Start here

Protocol flows

Storefront and operations

Mapping templates

The module ships editable starter mappings for generic OCI and cXML as well as SAP, SAP Ariba, Coupa and Oracle-oriented projects. Start with the Template Selection Guide, then validate the copied rules against the buyer's current specification. A template name is not a certification for that platform or buyer.

Add-ons

  • Iframe Compatibility prepares an authenticated PunchOut session for procurement platforms that embed the Magento shop in an iframe.
  • Sample Data installs a connected OCI and cXML example workflow for local, demo and staging environments.

See the Add-Ons overview before installing either package. The normal top-level PunchOut flow needs neither add-on.

Important boundaries

  • PunchOut transfers a shopping cart; it does not replace the buyer's approval or purchase-order process.
  • Returning a cart does not place an order. Order creation begins only when an authenticated cXML OrderRequest reaches the inbound-order endpoint and the effective processing mode is Create Magento Order.
  • Buyer-profile inbound-order values override the selected Store view. Leave an override empty when the buyer should inherit Store-view configuration.
  • Confirmation, ASN and invoice documents use their own HTTPS endpoints. The browser cart-return URL is never reused for server-to-server documents.
  • Fulfilment documents use durable buyer and order routing. They remain deliverable after the short-lived shopping session has expired.
  • SAP Ariba, Coupa and Oracle requirements vary by tenant and buyer. Treat the supplied mappings as a starting point.
  • Project-specific actor and permission behavior can be added through the public service contracts and Magento events without modifying the package.

For a failed request, begin with Common Issues and the Error Catalog.