Install the tag

This page shows how to put the punchout.dev script tag on your shop and what to configure so that the browser and punchout.dev accept it.

The tag

The portal shows the tag on the shop’s Embed tab under Script tag. It looks like this:

<script async src="https://js.punchout.dev/pob.js" data-shop-id="pob_live_…"></script>

Part	Meaning
src	The script, served from js.punchout.dev. The Embed tab shows it as Snippet URL.
async	The script never blocks the page from rendering.
data-shop-id	Your Shop ID, pob_live_ plus 22 characters. It is public: it names the shop, it does not authorize anything.

A tag without data-shop-id does nothing.

Put the tag on every page of the shop, ideally in the layout template before </body>. A punchout lands on your landing page, the buyer browses from there to the cart, and the tag must be present on every page along the way.

Where the tag goes

The three shop plugins print the tag themselves. With a plugin installed, do not paste the tag as well, or every page carries two tags. The Embed tab offers the plugin download and the install steps when General → Shop platform is set to Shopware, WooCommerce or Magento.

Without a plugin, where to paste the tag depends on your theme. The hints below describe where shops on each platform usually put it. punchout.dev has not checked them for your theme.

Shopware

1. On the Embed tab, download the plugin and upload it in Shopware under Extensions.
2. Activate it and enter the Shop ID and the Snippet URL in its configuration.

The plugin also marks the cart for cart detection and handles auto-login; see Shopware 6. Without the plugin, shops usually put the tag in the storefront theme’s footer or add it through a tag manager.

WooCommerce

1. On the Embed tab, download the plugin. In WordPress, open Plugins, add a new plugin with Upload Plugin and activate it.
2. Under WooCommerce → punchout.dev, enter the Shop ID, the Snippet URL and the public key lines.

The WooCommerce page has the details. Without the plugin, shops often put the tag in the theme’s footer.php, or in a script field that some themes offer in the Customizer.

Magento

1. On the Embed tab, download the module and unpack it into app/code. The archive already contains PunchoutDev/Bridge.
2. Run the commands below, then enter the Shop ID, the Snippet URL and the public key lines under Stores → Configuration → punchout.dev.

bin/magento module:enable PunchoutDev_Bridge
bin/magento setup:upgrade
bin/magento cache:flush

More on the module in Magento 2. Without the module, shops usually add the tag to the footer scripts of the design configuration under Content → Design → Configuration.

Any other shop

Copy the tag into the shop’s layout template, or add it through a tag manager. On Shopify, shops usually put it in the theme’s theme.liquid (Online Store → Themes → Edit code). Then let punchout.dev find your cart with a setup link (Cart detection), or mark the cart yourself by adding the attribute data-punchout-cart to the element that holds the line items. If you want to build more than the tag, such as auto-login, read Your own integration.

Allowed origins

punchout.dev works only on the origins listed for the shop. Set the list on the General tab under Allowed origins.

Rule	Detail
Format	https://shop.example: scheme, host and port, no path, no query
Matching	Exact. https://www.shop.example and https://shop.example are two origins; list both if both serve the shop
Count	1 to 5 origins
In production	https and a public hostname
First entry	Where punchout launches and setup links land

On a page whose origin is not listed, no punchout runs and the tag stays silent.

Cart URL patterns

General tab → Advanced settings → Cart URL patterns takes up to 10 regular expressions, such as ^/checkout/cart. punchout.dev matches them against the page’s path and query, ignoring case.

The patterns apply only while the shop has neither the plugin marker nor a Container selector (Cart detection). In that case they decide on which pages the panel reads the cart:

• With patterns set, only pages whose address matches one of them count as the cart.
• Without patterns, the panel recognizes cart pages on its own, by their usual addresses and by the page’s content.

Your patterns also decide which pages count as cart pages for the warning “The cart is no longer being found” on the Usage tab. Once the cart is marked or detected, the patterns no longer limit where the cart is read.

Content Security Policy

If your shop sends a Content-Security-Policy header, it must allow four sources, or the browser blocks the panel or the transfer. The Embed tab prints the four lines for your shop under Content Security Policy:

script-src https://js.punchout.dev
connect-src https://api.punchout.dev
style-src 'unsafe-inline'
form-action https://procurement.customer.example:*

Directive	Why
script-src	The panel loads from js.punchout.dev.
connect-src	The panel talks to api.punchout.dev.
style-src 'unsafe-inline'	The panel’s styles are inline.
form-action	The cart is handed to the buyer system from the shop page. A strict form-action blocks it without any visible error.

The portal builds the form-action line from General tab → Allowed return hosts, with one https://<host>:* source per host. The port is open (:*) because punchout.dev compares host names only and SAP systems often answer on ports other than 443. While Allowed return hosts is empty, the portal shows the placeholder https://buyer-system.example. Replace it with the hosts of your buyers’ systems.

Caution

The test punchout returns its cart to https://api.punchout.dev. While you use it, form-action must also allow https://api.punchout.dev. If your shop restricts Allowed return hosts, list api.punchout.dev there as well, and the Embed tab’s form-action line will include it.

Add these sources to the directives your policy already has. Do not replace your policy with these lines.

Check that the tag is live

A plain page view shows nothing, because the tag stays silent without a punchout or a setup link. The reliable check is the next step: create a setup link and detect your cart (Cart detection). A successful detection proves that the tag runs on your cart page.

The checklist step Snippet embedded on the Setup tab turns green after the shop’s first successful cart detection through a setup link or its first punchout launch. A hosted OCI, cXML or IDS Connect launch counts too. It reaches punchout.dev before your shop opens, so a green step alone does not prove that the tag is installed. Check now on the step reloads it, and the Cart tab shows the time under Snippet first seen.

What the tag does on a normal visit

Nothing. Without a punchout or a setup link, the tag shows no panel and sends nothing over the network.

It becomes active in two cases only:

• A punchout. A buyer system has launched the shop. The tag shows the panel, reads the cart when the buyer opens the cart page, and hands it over when the buyer clicks. A punchout lasts four hours at most.
• Setup mode. You opened a setup link. See Cart detection.

The tag’s privacy promises:

• It reads none of the shop’s cookies.
• It sends nothing without a running punchout or setup link.
• It never puts a secret in a URL, and it removes the launch parameters from the address bar.
• It hands the cart only to an http or https address.

More in Security and privacy.