Setting up PunchOut for Vendure - the complete guide | Create OCI and cXML PunchOut Catalogues | PunchCommerce ![](//analytics.punchcommerce.de/matomo.php?idsite=1&rec=1) Good to know Setting up PunchOut for Vendure - the complete guide =================================================================== Do you have a Vendure shop and want to connect it to the procurement systems of your key accounts via PunchOut? This guide will take you through the entire setup process - from the plugin installation in Vendure to the final configuration in the PunchCommerce dashboard. At the end, you can test the connection with the integrated PunchOut simulator without having to wait for your customer's IT. If you do not yet know what PunchOut is or how the Gateway Mode works: First read our \[Vendure integration announcement\](https://www.punchcommerce.de/de/journal/2026/neue-technologie-partnerschaft-punchout-anbindung-fur-vendure-shops) - there we explain the process at a glance. 30.04.2026 · Reading time 5 minutes ![Setting up PunchOut for Vendure - the complete guide](/storage/media/Vendure Guide.png) Requirements ------------ Before you start, you need three things: - A running **Vendure store** (v3.x or newer) with a storefront that you can customise. - A **PunchCommerce account**. Don't have one yet? [30-day free trial](https://www.punchcommerce.de/register). - Information about which **protocol** your customer expects - usually cXML (SAP Ariba, Coupa, Jaggaer), OCI (SAP environments in the DACH region) or IDS Connect (German wholesale, e.g. SHK and electrical). Part 1: Installing and configuring the Vendure plugin ----------------------------------------------------- ### Step 1 - Install the plugin Install the official community plugin via the package manager of your choice: ```bash npm install @vendure-community/punchout-gateway-plugin ``` ### Step 2 - Add the plugin to the Vendure configuration Add the plugin to your `vendure-config.ts`: ```typescript import { PunchOutGatewayPlugin } from '@vendure-community/punchout-gateway-plugin'; export const config: VendureConfig = { plugins: [ PunchOutGatewayPlugin.init({ // default values work immediately - // optional customisations see below }), ], }; ``` The plugin has everything the integration needs: a separate authentication strategy for PunchOut sessions, an active shopping basket assignment per session and a GraphQL mutation for the shopping basket transfer. ### Step 3 - Optional configuration In most cases, the default values are sufficient. You can customise three options if required: OptionDefaultWhen to customise?`apiUrl``https://www.punchcommerce.de`Only for self-hosted or staging instances`shippingCostMode``'nonZero'`If shipping costs should always (`'all'`) or never (`'none'`) be transferred`productFieldMapping`All products as pieces (`PCE`)If your catalogue contains products with different units (kg, litres, etc.)An example of product field mapping: Suppose you sell both individual parts and bulk goods. Then you can read the unit of measure per product from a Vendure custom field: ```typescript PunchOutGatewayPlugin.init({ productFieldMapping: { unit: { customField: 'punchOutUnit', default: 'PCE' }, unit_name: { customField: 'punchOutUnitName', default: 'Piece' }, weight: { customField: 'productWeight', default: 0 }, }, }) ``` If the custom field for a product is empty, the configured fallback value takes effect - a principle that you are also familiar with from field mapping in PunchCommerce. ### Step 4 - Assign customers in Vendure The plugin adds a new field to the Vendure customer object: **"PunchOut Customer ID (uID) "**. Open the customer in the Vendure admin and enter the same identifier that you later assign as "Customer Identification" in the PunchCommerce dashboard. The system uses this field to recognise which Vendure customer belongs to which PunchOut session. Part 2: Customise the storefront -------------------------------- Since Vendure works headless, your frontend needs three customisations. We describe the concept here - the complete code examples with GraphQL mutations can be found in the [official plugin documentation](https://docs.vendure.io/current/community-plugins/punch-out-gateway-plugin). It's even quicker with the **finished demo storefront** from the Vendure team: [vendurehq/punchcommerce-storefront-demo](https://github.com/vendurehq/punchcommerce-storefront-demo). It contains all three customisations as a working reference implementation. ### Customisation 1 - PunchOut landing page Create a route (e.g. `/punchout`) to which PunchCommerce will redirect the shopper. This page must do three things: - Read the parameters `sID` (session ID) and `uID` (customer identifier) from the URL. - Save the `sID` for the duration of the session - preferably in `sessionStorage` so that parallel browser tabs retain their own sessions. - Call the `authenticate` mutation with the PunchOut strategy and, if successful, redirect to the shop home page. ### Customisation 2 - Session-bound shopping cart All shopping basket operations - add item, change quantity, remove, display shopping basket - must include the parameter `activeOrderInput` with the current `sID`. This ensures that the shopping basket remains assigned to the correct PunchOut session. This applies to the mutations `addItemToOrder`, `adjustOrderLine`, `removeOrderLine` and the query `activeOrder`. Without this parameter, items end up in the regular shopping basket instead of in the PunchOut session. ### Adjustment 3 - Shopping basket transfer instead of checkout Replace the normal checkout flow with a "Transfer shopping basket" button. This calls the mutation `transferPunchOutCart` and transfers the `sID`. After a successful transfer, the order changes to "Transferred" status in Vendure - the shopping basket is archived and a new session starts with an empty shopping basket. ### Note: iFrame mode If the procurement system embeds your shop in an iFrame (instead of opening it in a new window), you must also set the session cookies to `SameSite=None; Secure` and remove the `X-Frame-Options` header during PunchOut sessions. Details can be found in the [plugin documentation](https://docs.vendure.io/current/community-plugins/punch-out-gateway-plugin#4-iframe-support-if-applicable). Part 3: Configuring the PunchCommerce dashboard ----------------------------------------------- ### Step 1 - Create customers Create a new customer in the PunchCommerce dashboard. Assign a unique **"Customer Identification "** - this is the `uID`, which must also be stored in the Vendure Admin for the customer object. ### Step 2 - Enter Entry Address Enter the URL of your PunchOut landing page, e.g. `https://ihr-shop.de/punchout`. PunchCommerce forwards the shopper to this address and automatically appends the parameters `sID` and `uID`. ### Step 3 - Select protocol and configure field mapping Select the protocol that your customer expects: - **cXML** for SAP Ariba, Coupa or Jaggaer - **OCI** for SAP procurement systems in the DACH region - **IDS Connect** for the German wholesale trade (SHK, electrical) and tradesman software You then assign the shop attributes (EAN, SKU, short description, price) to the PunchOut fields in the field mapping. This works via drag & drop. If a mandatory field in the shop is empty, a configurable fallback value takes effect - this ensures data quality without you having to adapt your source system. ### Step 4 - Testing with the PunchOut simulator Before you approach your customer: Use the integrated PunchOut simulator in PunchCommerce. It simulates a complete session - from forwarding via the shopping basket to the transfer back to the procurement system. You can see immediately whether the mapping, prices and product data arrive correctly. Experience has shown that this saves at least one round of coordination with your customer's IT department. Summary: What happens where --------------------------- TaskWhereEffortInstall and configure pluginVendure~10 minutesCustomise storefront (3 places)Your frontend codeDepending on projectCustomer mapping (uID)Vendure-Admin + PunchCommerce~5 minutesProtocol and field mappingPunchCommerce dashboard~15 minutesTesting with simulatorPunchCommerce dashboard~5 minutesThe configuration on the PunchCommerce site takes less than 30 minutes. The biggest variable factor is the storefront customisation - here the [Demo-Storefront](https://github.com/vendurehq/punchcommerce-storefront-demo) speeds up the start considerably. Next step --------- Would you like to discuss the integration with your specific setup - or get started straight away? We will show you in a brief discussion what the setup looks like in practice. **[Book an appointment now →](https://account.netzdirektion.de/appointments/punchcommerce)** If you have any questions or suggestions, just send us an email or call us at [+49 6142 / 953 80 - 60](tel:061429538060). We appreciate your feedback! [Back to the journal](https://www.punchcommerce.de/en/journal) #### You might also be interested in these posts - [Our JTL plugin is now available in the JTL Extension Store](https://www.punchcommerce.de/en/journal/2026/our-jtl-plugin-is-now-available-in-the-jtl-extension-store "To the post Our JTL plugin is now available in the JTL Extension Store") - [New Shopware integration: link customers directly from PunchCommerce](https://www.punchcommerce.de/en/journal/2026/new-shopware-integration-link-customers-directly-from-punchcommerce "To the post New Shopware integration: link customers directly from PunchCommerce") - [PunchOut Level 1 vs. Level 2 with Ariba®: These are the differences](https://www.punchcommerce.de/en/journal/2023/punchout-level-1-vs-level-2-with-ariba-these-are-the-differences "To the post PunchOut Level 1 vs. Level 2 with Ariba®: These are the differences") Fancy a Test? Start the non-binding 30-day test phase. -------------------------------------------------------- [ Create a PunchOut catalogue now ](https://www.punchcommerce.de/register) [ PunchCommerce® ist ein Produkt der ![Netzdirektion GmbH](https://www.punchcommerce.de/static/netzdirektion-logo.png "PunchCommerce® ist ein Produkt der netzdirektion | Gesellschaft für digitale Wertarbeit mbH") ](https://netzdirektion.de) [Give feedback now - your opinion helps us to become even better!](https://easy-feedback.de/umfrage/1883200/5FuM95 "Your opinion helps us to become even better!")