B2B Punchout on Magento and Hyva: Implementing cXML and OCI Procurement Catalogs

Punchout lets a corporate buyer shop your Magento or Adobe Commerce catalog from inside their own procurement system, then push the finished cart back to that system as a requisition for approval. The store authenticates the buyer, shows their contract pricing, and returns the cart as a structured document. On Magento you build it with the B2B foundations plus a cXML or OCI layer, and on a Hyva frontend the shopping session needs deliberate handling.

For large distributors and manufacturers, punchout is not a nice-to-have. It is often the gate that decides whether a purchasing department can buy from you at all. This guide covers how the flow actually works, which protocol you need, what Adobe Commerce gives you for free, and the storefront details that catch teams out on a Hyva build.

What punchout is, and why enterprise buyers demand it

A punchout catalog connects your storefront to a buyer’s e-procurement platform such as SAP Ariba, Coupa, Jaggaer, or Oracle. Instead of maintaining a static uploaded catalog inside their procurement tool, the buyer “punches out” to your live store, sees real inventory and their negotiated prices, builds a cart, and transfers it back. Approval, budget checks, and the purchase order all happen inside their system, where their controls already live.

The reason procurement teams insist on this is control. Their spend policy, approval chains, and general-ledger coding all run inside Ariba or Coupa. They will not let hundreds of buyers place cards-out orders on a supplier website. If you cannot present a punchout catalog, you are frequently removed from the approved-vendor list before a single order is placed. That is why B2B merchants selling into hospitals, universities, government, and Fortune 500 procurement treat it as table stakes.

The message flow, step by step

Punchout is a sequence of documents exchanged between the buyer’s system and your store. The mechanics are consistent whether you run Magento, Adobe Commerce, or another platform. Here is the cXML version, which is the dominant one in North America.

1. PunchOutSetupRequest. The buyer clicks your catalog inside their procurement system. That system posts a PunchOutSetupRequest to your store containing the buyer’s identity, a shared secret, and two return URLs (BrowserFormPost for the cart, plus a Postback endpoint).
2. Authentication and session start. Your store validates the credentials against the shared secret or certificate you exchanged during onboarding, then replies with a PunchOutSetupResponse containing the URL of the live shopping session it just created.
3. Shopping. The buyer is redirected into that session on your storefront and shops normally, seeing their company’s contract pricing. This is where the Hyva frontend does its work.
4. PunchOutOrderMessage. When the buyer clicks the transfer button, your store serializes the cart into a PunchOutOrderMessage and returns it through a hidden browser form-post to the procurement system. The buyer never leaves their tool.
5. OrderRequest. After internal approval, the procurement system sends a cXML OrderRequest (the actual purchase order) to your store, which creates the sales order.

OCI, SAP’s Open Catalog Interface, does the same round trip with HTTP form fields and URL parameters rather than structured XML. It is simpler to stand up but carries less data, which matters for the document exchange that follows the cart return.

cXML versus OCI: pick the protocol your buyers use

You do not choose the protocol. Your buyer’s procurement platform does, and a mid-market supplier commonly ends up supporting both because different customers run different systems. The practical differences:

The rule of thumb: if the buyer runs SAP procurement, expect OCI; if they run almost anything else in the US, expect cXML. Support both if you sell across a mixed base. Note the practical gap in OCI: because it does not carry order confirmations or invoices natively, you either bolt on cXML or EDI for those documents or handle them out of band.

There is also a maturity ladder inside cXML itself. Level 1 punchout returns line items with descriptions and prices. Level 2 punchout lets a buyer search your catalog and punch out directly to a specific product or category from inside their procurement search, which enterprise buyers increasingly expect. Scope which level you owe each account before you quote the work.

What Adobe Commerce gives you, and what it does not

Punchout rides on top of B2B account structure. You cannot show contract pricing to a buyer you cannot identify. Adobe Commerce B2B supplies the pieces you need: company accounts, shared catalogs with company-specific pricing, requisition lists, negotiated quotes, purchase orders, and approval workflows. The Adobe Commerce shared catalog documentation explains how a gated catalog maps custom pricing to specific companies, which is exactly the pricing a punchout session must render.

What Adobe Commerce does not give you is the punchout protocol layer itself. Core Magento and Adobe Commerce ship no cXML or OCI endpoint. You get there one of two ways:

• A marketplace extension. Several vendors publish punchout suites for Magento 2 and Adobe Commerce that handle both cXML and OCI, connect to the major procurement networks, and map the cart to a PunchOutOrderMessage. These are the fastest path when your requirements are standard.
• A custom integration. When you have unusual pricing logic, non-standard UNSPSC coding, a middleware layer, or an ERP that owns pricing, a bespoke integration built by a Magento development team gives you control the extension cannot. This is the right call for complex enterprise accounts.

Magento Open Source can also do punchout, but you lose the native B2B company and shared-catalog objects, so you rebuild that scaffolding first. On Adobe Commerce, enabling B2B features is the prerequisite step before any punchout work begins.

What changes on a Hyva storefront

The punchout round trip is mostly a backend concern, but stage three, the shopping session, happens on your storefront. If that storefront is Hyva, a few things need deliberate design.

Session mode and hidden UI. A punchout session is not a normal browsing session. The buyer must not see a standard checkout, guest registration, or payment step, because ordering happens in their procurement tool. Your Hyva theme needs a punchout mode that swaps the checkout call to action for a “transfer cart” button and suppresses account-creation prompts. Because Hyva renders with Alpine.js and native JavaScript rather than the Luma stack, this is a clean conditional in the template layer rather than a fight with legacy UI components.

The return form-post. The PunchOutOrderMessage goes back through a hidden auto-submitting form. Handle that submit carefully in Alpine so it fires once, posts to the exact BrowserFormPost URL from the setup request, and does not get intercepted by any single-page navigation behavior on the theme.

Pricing and full page cache. Punchout buyers see company-specific pricing, which is customer-private data. That must never land in the shared full page cache. Render contract prices through a private-content or uncached block so one company’s negotiated rate is never served to another. This is the same discipline any B2B Hyva build needs, and getting it wrong is the most common and most damaging punchout bug.

Performance still matters. A procurement buyer punching in from Coupa judges your store on the same Core Web Vitals as anyone else. A Hyva frontend is what keeps that session fast while it renders per-company pricing, and speed is a real factor in whether buyers keep coming back rather than switching to a competing approved vendor.

Punchout support across platforms

Adobe Commerce is the deepest B2B platform for punchout, but it is not the only one. If you are choosing a platform partly on procurement fit, here is the practical landscape.

If your roadmap points toward Shopify development, BigCommerce development, or Shopware development, all three can support punchout, but the depth of native B2B pricing and account hierarchy is where Adobe Commerce still leads for complex procurement. Choose the platform on the whole B2B picture, not punchout alone, and lean on your agency’s technology partner ecosystem to fill the procurement-network gaps.

A realistic implementation sequence

A punchout project that goes smoothly tends to follow this order:

1. Confirm B2B foundations. Company accounts, shared catalogs, and customer-specific pricing must be live and correct first.
2. Inventory the buyer requirements. For each account: cXML or OCI, Level 1 or Level 2, which procurement platform, what product identifiers (SKU, UPC, UNSPSC), and whether they need order confirmations and invoices.
3. Stand up the protocol layer. Extension or custom, with the shared-secret exchange and endpoint URLs configured per buyer.
4. Build the storefront punchout mode. The Hyva session handling, hidden checkout, and transfer button.
5. Test in the buyer’s sandbox. Ariba, Coupa, and Jaggaer all provide test environments. Validate the full round trip, including the returned OrderRequest, before go-live.
6. Onboard account by account. Each new procurement customer is its own credential exchange and validation cycle.

The pattern that fails is treating punchout as a one-time switch. It is a per-account onboarding capability, and your store and processes need to support adding buyers over time.

FAQ

Do I need Adobe Commerce, or will Magento Open Source work for punchout?

Both can do punchout. Adobe Commerce gives you native company accounts, shared catalogs, and company-specific pricing, which punchout depends on, so you build only the protocol layer. On Magento Open Source you rebuild that B2B scaffolding first, which adds cost. For any serious B2B program, Adobe Commerce is usually the more economical starting point once you account for the rebuild.

How long does a punchout integration take to build?

The protocol layer for a single procurement platform, on a store that already has B2B accounts and shared catalogs working, is typically a few weeks including sandbox testing. Timelines stretch when pricing logic lives in an ERP, when you need both cXML and OCI, when Level 2 search punchout is required, or when several buyers must be onboarded at launch. Scope it per requirement rather than as one fixed number.

What is the difference between Level 1 and Level 2 punchout?

Level 1 returns a cart of line items with descriptions and prices to the procurement system. Level 2 lets the buyer search your catalog from inside their procurement search and punch out directly to a specific product or category. Many enterprise buyers now expect Level 2 because it keeps the search experience inside their tool.

Does punchout work with a Hyva frontend?

Yes. The punchout round trip is largely a backend flow, and Hyva handles the shopping session cleanly. The work is building a punchout mode in the theme that hides the normal checkout, shows a transfer-cart action, and keeps company-specific pricing out of the shared full page cache. Hyva’s Alpine.js model makes those conditionals simpler than they were on Luma.

Can one store serve buyers on both Ariba and SAP procurement?

Yes, and many do. Ariba and most US platforms use cXML; SAP procurement commonly uses OCI. A store that sells across a mixed base supports both protocols and negotiates credentials with each buyer separately. Plan for both if your customer list spans SAP and non-SAP procurement.

Where to start

If enterprise procurement is on your roadmap, get the B2B foundations right before you touch punchout, then scope the protocol layer against your actual buyers rather than a generic checklist. Bemeir is a Brooklyn Magento and Adobe Commerce agency and the USA’s first Hyva Gold Partner, and you can read more about Bemeir and how the team works as an extension of yours. When you are ready to map your procurement requirements to a build plan, start at Bemeir.