PunchOut for Medusa v2: OCI &amp; cXML via plugin | PunchCommerce                       ![](//analytics.punchcommerce.de/matomo.php?idsite=1&rec=1)

  [Skip to content](#main-content)

  Integration · Medusa v2 PunchOut for Medusa. Your customer requires PunchOut, you run Medusa. You deliver with a plugin.
==================================================================================================

 Your key account wants to order in your shop straight from its procurement system, via OCI, cXML or IDS Connect. With the PunchCommerce plugin for Medusa v2 you connect your shop to the gateway: you install the plugin in the back end, add the entry and the cart transfer to your storefront and create the customer in PunchCommerce.

 [ Start free trial ](https://www.punchcommerce.de/register) [ See the setup ](#setup)

30 days free · no credit card · cancel anytime

  Protocols: OCI, cXML and IDS Connect 3

 for the plugin €0

 per customer per month, plus VAT €49

 Plugin

One plugin for your Medusa back end, the gateway for your customer
------------------------------------------------------------------

The plugin connects your Medusa back end to the PunchCommerce gateway; your storefront transfers the cart in the PunchCommerce format, and PunchCommerce handles the protocol communication.

 For Medusa v2### PunchCommerce plugin for Medusa

Plugin for the gateway connection via OCI, cXML and IDS Connect 2.5, plus:

- Parallel PunchOut sessions with separate carts
- Customer link via a widget in the Medusa admin
- Item lookup, search and cart restore from the procurement system

  Version Medusa 2.13.6 or later

 Runtime Node.js 20 or later and a storefront you can modify

 Source npm package `@punchcommerce/punchcommerce-medusa-plugin`

 License PunchCommerce Standard Module License, free of charge in connection with PunchCommerce

 Account PunchCommerce Business or Enterprise

  [ View on npm (opens in a new window) ](https://www.npmjs.com/package/@punchcommerce/punchcommerce-medusa-plugin) [Plugin documentation](https://www.punchcommerce.de/en/documentation/medusa-plugin)

 Configuration medusa-config.ts

 ```
plugins: [
  {
    resolve:
      "@punchcommerce/punchcommerce-medusa-plugin",
    // optional
  },
],
```

In addition, you register the plugin's auth provider with the id “punchcommerce” in the Auth module. In the Medusa admin you link the customer via the PunchCommerce widget to the same uID as in PunchCommerce.

 Medusa separates the back end from the storefront, meaning the interface in which your customers shop. The plugin only works in the back end, so your storefront takes on three tasks: it receives the buyer on an entry route, for example `//punchcommerce/authenticate`, creates a separate cart for each PunchOut session and, instead of the checkout, shows a page that transfers the cart to the procurement system at the push of a button. The examples in the documentation build on the [Next.js Starter Template by Medusa (opens in a new window)](https://github.com/medusajs/nextjs-starter-medusa) on GitHub.

 The gateway handles the protocols: it talks to your customer's procurement system, for example SAP Ariba, Coupa, Jaggaer or SAP SRM, via [OCI PunchOut](https://www.punchcommerce.de/en/oci-punchout) or [cXML PunchOut](https://www.punchcommerce.de/en/cxml-punchout) and returns the cart in the right format. You set the protocol per customer in PunchCommerce. You connect plumbing, heating and electrical trade businesses via [IDS Connect](https://www.punchcommerce.de/en/ids-connect) from the same Medusa installation.

 Do you run further shops on other systems? Under [Integrations](https://www.punchcommerce.de/en/integrations) you will find all plugins, extensions and connection options.

 Setup

From plugin to go-live in six steps
-----------------------------------

The first five steps come from the plugin documentation; field mapping and the simulator are added by PunchCommerce. Steps three and four concern your storefront, which is where most of the work lies with Medusa. You do not have to implement a PunchOut protocol for this.

1. 1 You · back end### Install the plugin

    Install the npm package `@punchcommerce/punchcommerce-medusa-plugin` and add it as a plugin in medusa-config.ts. Without the punchcommerceUrl option the plugin connects to punchcommerce.de.
2. 2 You · back end### Register the auth provider

    In the Auth module, also register the plugin's auth provider with the id `punchcommerce`. The disableSessionValidation option is meant for local development only and stays switched off in production.
3. 3 You · storefront### Create the entry route

    Create a route such as `//punchcommerce/authenticate` in your storefront. It reads the session ID (sID) and the customer identifier (uID) from the address, logs the buyer in via the Medusa SDK, creates a new cart and stores the sID in its metadata.
4. 4 You · storefront### Replace checkout with transfer

    Replace the checkout with a PunchOut page. It loads the prepared cart via `/store/punchout/basket`, shows it for review and sends it at the push of a button to the address the plugin returns for this.
5. 5 You · PunchCommerce### Create and link the customer

    Create your customer in PunchCommerce with the OCI, cXML or IDS Connect protocol, a unique customer identifier and the address of your entry route as the entry address. In the Medusa admin, enter the same customer identifier as the uID in the PunchCommerce widget on the customer page.
6. 6 You · PunchCommerce### Test and hand over

    Use the visual field mapping to define which shop data lands in which PunchOut field, and test the flow with the simulator in PunchCommerce. Then pass the access details on to your customer.

###   What you need from your customer

- The protocol of their procurement system: OCI, cXML or IDS Connect
- The product classification key their system expects
- The units of measure they order in
- Access to their test system for the trial run

###   What you send your customer

- The PunchOut URL from PunchCommerce
- The access details, for cXML `Identity` and `SharedSecret`
- The access guide as a PDF from PunchCommerce

 Features

What the plugin offers your PunchOut customers
----------------------------------------------

The features are taken from the plugin documentation, the field mapping from PunchCommerce. Because of OCI and cXML requirements, the plugin shortens item names to 39 characters; it also transfers the full title in the product data. After the transfer, the cart in Medusa stays as it is; the order itself comes later via PunchCommerce from your customer's system.

### Login via the uID

The plugin brings its own auth provider. It checks the session ID with PunchCommerce and logs the buyer in as the Medusa customer linked to the uID that was sent.

### Link in the Medusa admin

A widget on the customer page shows the link to PunchCommerce. If a uID is already assigned to another customer, the widget reports an error. If the customer is deleted, the link is removed.

### Parallel sessions

Each PunchOut session gets its own cart. The same customer can open several sessions at once; carts they created outside of PunchOut remain untouched.

### Net, gross and tax rate

Each item is sent to PunchCommerce with net and gross total, net unit price and tax rate, plus item number, title, description, image and currency.

### Item lookup, search, restore

If the procurement system calls up an item directly, searches the shop or restores an earlier cart, the plugin processes these calls. Your storefront decides where the buyer goes next.

### Visual field mapping

In PunchCommerce you visually map per customer which data lands in which field on your customer's side, instead of configuring it in code.

  Not supported: units per variant, all items are currently sent as pieces, and shipping costs as a separate item. Supported: item lookup, search and cart restore from the procurement system.

 Pricing

What PunchOut for Medusa costs
------------------------------

The plugin is free of charge; its license permits use in connection with PunchCommerce. You pay per customer you connect in PunchCommerce. Hosting is GDPR-compliant in Germany.

 For your case Supplier · self-service setup### PunchCommerce Business

Gateway connection of your Medusa shop via OCI, cXML and IDS Connect, set up by you, without an agency. Three connected customers cost €147 per month, plus VAT.

 €49 per customer per month, plus VAT

Without your own shop: plus the Hosted Catalog add-on, €50 per customer per month, plus VAT.

 [ Start free trial ](https://www.punchcommerce.de/register)30 days free · no credit card · cancel anytime

 [Compare plans and pricing](https://www.punchcommerce.de/en/features-and-pricing)

 With SLA &amp; operational responsibility### PunchCommerce Enterprise

For suppliers who need availability with an uptime guarantee, defined escalation paths and someone responsible for operating their PunchOut connections.

 Custom based on SLA level and number of connections

 [ Schedule a consultation (opens in a new window) ](https://account.netzdirektion.de/appointments/punchcommerce)30 min · remote · with the founder

 [See PunchCommerce Enterprise](https://www.punchcommerce.de/en/enterprise)

 FAQ

Frequently asked questions about PunchOut for Medusa
----------------------------------------------------

What Medusa teams want to know before their first PunchOut connection.

 ###   Where do I get the PunchOut plugin for Medusa? +

 The plugin is called @punchcommerce/punchcommerce-medusa-plugin and is installed as an npm package. It is published by netzdirektion, the company behind PunchCommerce. Its license (PunchCommerce Standard Module License) permits use free of charge, including commercial use, exclusively in connection with PunchCommerce.

###   What are the requirements for my Medusa shop? +

 You need Medusa 2.13.6 or later, Node.js 20 or later and a storefront you can modify. Because the plugin only works in the back end, an entry route, a separate cart per PunchOut session and a transfer page instead of the checkout belong in your storefront.

###   Which PunchOut protocols does the Medusa plugin support? +

 The plugin connects your shop to the PunchCommerce gateway, and the gateway speaks OCI, cXML and [IDS Connect](https://www.punchcommerce.de/en/ids-connect). You set the protocol per customer in PunchCommerce. Your storefront transfers the cart in the PunchCommerce format; PunchCommerce handles the communication with your customer's system.

###   How does the shop know which customer is buying? +

 In the Medusa admin you link the customer via the PunchCommerce widget to the same uID you enter in PunchCommerce as the customer identifier. On entry, PunchCommerce appends the parameters sID (session ID) and uID to your entry address. The plugin's auth provider checks the sID with PunchCommerce and logs the linked customer in.

###   What do I check if the entry or the cart transfer does not work? +

 If the login reports “No PunchCommerce Identity found.”, no customer in Medusa is linked to this uID yet; check the spelling in both systems. If the plugin rejects the transfer, the cart often lacks the sID in its metadata (punchcommerce_session_id), for example because the storefront reuses an existing cart instead of creating a new one. If the cart does not arrive at PunchCommerce, check whether your form wraps the items in { basket: […] }. The option disableSessionValidation is meant for local development only and must be switched off in production.

###   What does PunchOut for Medusa cost? +

 The plugin is free of charge. PunchCommerce Business costs €49 per connected customer per month, plus VAT. Three customers therefore cost €147 per month, plus VAT. If you need an SLA and operational responsibility, PunchCommerce Enterprise is the right plan.

  Get started

 Your customer is waiting for PunchOut. Deliver it from your Medusa shop.
--------------------------------------------------------------------------

 €49 per customer per month, plus VAT. Install the plugin, adapt the storefront, create the customer, send the access details, done.

 [ Start free trial ](https://www.punchcommerce.de/register)30 days free · no credit card · cancel anytime

 ![Patrick Dornbusch, founder of PunchCommerce](https://www.punchcommerce.de/static/patrick-dornbusch.webp)Patrick Dornbusch

Founder of PunchCommerce

Prefer to talk first? In 30 minutes we’ll work out which option suits your shop, your ERP and your customers’ procurement systems.

 [ Schedule a consultation  (opens in a new window) ](https://account.netzdirektion.de/appointments/punchcommerce)30 min · remote · with the founder

 PunchCommerce® is a product of [ ![netzdirektion | Gesellschaft für digitale Wertarbeit mbH](https://www.punchcommerce.de/static/netzdirektion-logo.png) (opens in a new window) ](https://netzdirektion.de) ![DEKRA seal: quality management according to ISO 9001](https://www.punchcommerce.de/static/dekra-netzdirektion-iso-9001.png) **ISO 9001:2015**
certified quality management

 netzdirektion | Gesellschaft für digitale Wertarbeit mbH · © 2020 - 2026
