Good to know Setting up PunchOut for Vendure - the complete guide

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.
• 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:

npm install @vendure-community/punchout-gateway-plugin

Step 2 - Add the plugin to the Vendure configuration

Add the plugin to your vendure-config.ts:

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:

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:

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.

It's even quicker with the finished demo storefront from the Vendure team: 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.

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

The configuration on the PunchCommerce site takes less than 30 minutes. The biggest variable factor is the storefront customisation - here the Demo-Storefront 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 →

If you have any questions or suggestions, just send us an email hallo@punchcommerce.de or call us at +49 6142 / 953 80 - 60. We appreciate your feedback!