cXML PunchOut Catalog Integration: A Technical Guide to Connecting Your B2B Portal

If you need the groundwork—what a PunchOut catalog is and how the buying flow works in plain terms—start with our PunchOut catalog guide. This article assumes that background and focuses on the integration itself: the cXML messages, the Level 1 and Level 2 distinction, and how the connection is built between a procurement system and a B2B portal.

1. WHAT cXML DOES IN A PUNCHOUT INTEGRATION
2. THE cXML MESSAGE FLOW
3. LEVEL 1 AND LEVEL 2 PUNCHOUT
4. HOW TO INTEGRATE PUNCHOUT WITH A B2B PORTAL
5. TAKING PUNCHOUT BEYOND THE CONNECTION
6. FAQS

cXML—Commerce eXtensible Markup Language—is the message format that carries a PunchOut session between the buyer's procurement system and the supplier's store. Where the buying experience is what the user sees, cXML is the conversation happening underneath it: a set of structured documents that the two systems POST to each other over HTTPS, each one a defined step in setting up the session and returning the cart.

A PunchOut integration relies on three cXML documents in particular:

• PunchOutSetupRequest—sent by the procurement system to open a session. It carries the buyer's credentials, the operation type, and the URL the supplier should post back to.
• PunchOutSetupResponse—the supplier's reply, containing the start-page URL where the buyer's session is waiting.
• PunchOutOrderMessage—sent back when the buyer finishes shopping, carrying the cart contents, quantities, and pricing into the procurement system for approval.

These are real-time, synchronous messages: each step waits on the one before it. Get the structure or the credentials wrong in any document and the session fails rather than degrading quietly, which is why the integration work is precise rather than approximate.

A single PunchOut session follows a fixed sequence of cXML exchanges between three parties—the buyer's procurement system, an integration gateway that translates and routes messages, and the supplier's B2B portal.

The order of events:

1. Session request. The buyer selects the supplier inside their procurement application. The procurement system generates a PunchOutSetupRequest and posts it—via the integration gateway—to the supplier's portal.
2. Session response. The portal validates the credentials and returns a PunchOutSetupResponse containing a unique start-page URL. That URL carries a session identifier, so when the buyer follows it they land in the portal already authenticated, with their account context and contract pricing applied.
3. The shopping session. The buyer browses the portal as themselves—their catalog, their negotiated prices, their availability—and builds a cart.
4. Cart return. Instead of checking out, the buyer transfers the cart. The portal generates a PunchOutOrderMessage and posts it back through the gateway to the procurement system, where it becomes a requisition subject to the buyer's approval rules.

The supplier's portal never completes the order itself. Final purchase-order issuance happens inside the procurement system once approvals clear—sometimes over a separate channel such as EDI—which keeps the buyer's governance intact and the supplier out of the buyer's internal workflow.

The flow above describes Level 1 PunchOut: the buyer launches a session, shops, and returns a cart. It works, but it requires the buyer to leave their procurement application and enter the supplier's store for every search.

Level 2 PunchOut removes that constraint. It lets the procurement system index supplier items directly, so buyers search and find products within their procurement application, then deep-link straight to the relevant product or category in the supplier's store rather than always landing on the home page.

Technically, Level 2 depends on two things: a catalog index file the supplier provides to the procurement system, and an added node in the PunchOutSetupRequest that names the specific item the buyer selected. When the request carries a <SelectedItem> node, the portal opens the session on that product instead of the storefront home page:

<PunchOutSetupRequest operation="create">
  <!-- credentials and post-back URL above -->
  <SelectedItem>
    <ItemID>
      <SupplierPartID>PN123456</SupplierPartID>
      <SupplierPartAuxiliaryID>ID98765746</SupplierPartAuxiliaryID>
    </ItemID>
  </SelectedItem>
</PunchOutSetupRequest>

The SupplierPartID (and optional SupplierPartAuxiliaryID) come from that index file; without a <SelectedItem> node, the request falls back to a standard Level 1 session. For most enterprise and public-sector buyers, Level 2 is the expectation—it makes the supplier's catalog feel native to the procurement tools they already use.

There are two ways to build the connection between a procurement system and a B2B portal, and the difference is largely one of who maintains the translation layer.

Custom peer-to-peer integration. The supplier and buyer build and host the connection themselves, mapping cXML documents directly between the two systems. It gives full control, but it's expensive to stand up and costly to maintain: someone has to own credential management, error handling, retry and fault logic, and the reliability of a connection that has to work around the clock—and that burden repeats for every new buyer and every procurement platform they run.

Managed gateway integration. A third-party gateway sits between the systems as a translator: the procurement system and the portal each speak to the gateway, and the gateway handles the cXML formatting, routing, and platform-specific quirks. This is the path most suppliers take, because one integration to the gateway opens connections to many procurement systems rather than one at a time.

A managed integration has three moving parts: the buyer's e-procurement system (Coupa, SAP Ariba, Oracle, Jaggaer, Workday, and the like), the supplier's B2B portal, and the gateway that carries cXML between them. On the portal side, the platform needs to expose the catalog, apply account-specific pricing within the session, generate the start-page URL, and produce a valid PunchOutOrderMessage on cart return.

For portals built on Virto Commerce, that gateway is Greenwing Technology. Virto's Greenwing integration provides more than 135 pre-built connectors to e-procurement platforms including Ariba, Coupa, Oracle, and Jaggaer, which means a Virto-powered portal can connect to institutional buyers without building and maintaining a custom cXML integration for each one. The portal exposes its catalog and pricing; Greenwing handles the cXML translation and routing to whichever procurement systems the buyer uses.

The integration is the technical foundation. What turns it into a procurement relationship that large accounts actually adopt is everything the portal applies inside the session—contract catalogs, account-specific pricing, organizational hierarchies, and approval governance—so that the cart returning to the procurement system is correct, compliant, and traceable from the start.

👉 For how Virto Commerce supports PunchOut as part of that broader procurement-driven model, see the PunchOut catalog integration feature page.