Troubleshooting
Each section starts with what you see, in the words the panel, the launch page or the portal uses, and lists the possible causes and how to fix them.
Where to look
Section titled “Where to look”- The panel. Its messages are quoted below, in English. On a German page it shows the German version.
- The browser’s console. It reports Content Security Policy violations and requests the browser blocked.
- The portal. The shop’s Usage tab shows the Daily budget, the Live sessions list and the warning “The cart is no longer being found”.
The panel does not appear
Section titled “The panel does not appear”During a punchout, the panel appears on every page of the shop, including pages without a cart. If it does not appear at all, check these causes:
| Cause | How to tell | Fix |
|---|---|---|
| The script tag is missing | The page source has no pob.js |
Add the tag from the Embed tab to the layout template. With a plugin: check Embed the snippet, Snippet URL and Shop ID. |
| The browser blocks the script or its requests | The console reports a Content Security Policy violation | Add the script-src, connect-src and style-src lines from the Embed tab, see Install the tag |
| There is no punchout | The page was opened directly, not from a buyer system | Start from the buyer system, or run a test punchout from the Setup tab |
The OCI catalog configuration fills FUNCTION |
The shop address the buyer system opens contains FUNCTION= with a value |
Leave FUNCTION empty in the catalog configuration. A hosted launch with a FUNCTION value shows “Access denied” instead, see below. |
| The shop’s address is not an allowed origin | The console reports a blocked cross-origin (CORS) request to api.punchout.dev |
Add the address under Allowed origins on the General tab. Scheme, host and port must match exactly: https://www.shop.example and https://shop.example are two origins. |
| The punchout has expired or ended | Four hours have passed since the launch, the cart was already transferred, or the buyer chose Back to procurement system | Start a new punchout |
| The tag carries another Shop ID | data-shop-id on the tag differs from the Shop ID on the Embed tab |
Correct the Shop ID in the tag or the plugin |
| The shop is inactive | Shop active is off on the General tab | Switch it on |
| A direct OCI launch carries a return address that is not allowed | The buyer system’s host is not under Allowed return hosts | See The transfer does not arrive |
If the panel shows “Punchout is not enabled for this shop yet. Please contact the supplier.” instead, see A launch says “Punchout not enabled”.
The panel says “No cart on this page”
Section titled “The panel says “No cart on this page””The full text is “No cart on this page. Add items to your cart and open it. The items are recognized there automatically.”
| Cause | Fix |
|---|---|
| The buyer is not on the cart page | Nothing to fix. The panel reads the cart once the buyer opens it. |
The cart page is not recognized as one. Without a plugin marker or a detected cart container, a page counts as the cart when its address contains cart, warenkorb, basket, panier or carrello, or when it shows a quantity field and a price. Once Cart URL patterns are set (General tab, Advanced settings), only those patterns count. |
Add a pattern that matches your cart URL, or run cart detection |
| The detected cart container is no longer found, usually after a theme update. The Usage tab warns “The cart is no longer being found”. | Click Detect the cart again and confirm the cart with a new setup link |
| A plugin’s marker does not reach the page | See the troubleshooting table of Shopware 6, WooCommerce or Magento 2 |
The panel says “Analysis failed.”
Section titled “The panel says “Analysis failed.””The panel shows “Analysis failed.” with a Retry button when it could not read the cart. Possible causes:
| Cause | Fix |
|---|---|
| The shop’s Daily budget is used up, or its Sandbox period has ended | See The daily budget is used up |
| The cart was analyzed too often in this punchout | Start a new punchout |
| The part of the page that was read holds no line items, for example an empty marker | Check the marker or run cart detection again |
| The page’s address is not under Allowed origins, for example a second domain of the shop | Add it on the General tab |
| A temporary failure | Click Retry after a moment |
| The cart changed after the review, before the transfer | Click Retry: the panel reads the cart again for a new review |
The transfer does not arrive
Section titled “The transfer does not arrive”The buyer clicks Transfer to procurement system, and the buyer system receives nothing.
| Cause | How to tell | Fix |
|---|---|---|
| The shop’s Content Security Policy blocks the form post | The console reports a form-action violation |
Add the form-action line from the Embed tab: one https://<host>:* source per entry under Allowed return hosts. While you use the test punchout, also allow https://api.punchout.dev. |
| The buyer system’s return host is not allowed at launch | Hosted OCI and IDS Connect launches show the “Access denied” page. A cXML buyer system reports Invalid PunchOutSetupRequest. After a direct OCI launch the panel does not appear. |
Add the host under Allowed return hosts on the General tab, or leave the list empty to allow any host. *.buyer.example matches subdomains only; list buyer.example itself separately if needed. |
| The return host was removed from the list after the launch | The panel disappears when the buyer clicks Transfer to procurement system | Add the host again and start a new punchout |
| The return address itself is malformed | The launch is refused: the “Access denied” page, or Invalid PunchOutSetupRequest in a cXML buyer system |
The buyer system must send an http or https address without user:password@, at most 2048 characters long |
To see what your shop sends, run a test punchout from the Setup tab. The portal shows the transfer item by item and as raw fields.
The buyer system opens the result in the wrong window
Section titled “The buyer system opens the result in the wrong window”The transfer opens in the window the launch chose. By default, OCI and cXML results open in the window that shows the shop, and IDS Connect results replace the whole browser window. If the buyer system shows the shop in a frame and the result appears inside it, set RETURNTARGET=_top in the OCI catalog configuration (or target=_top for IDS Connect). cXML has no such setting.
A launch shows “Access denied”
Section titled “A launch shows “Access denied””Hosted OCI and IDS Connect launches answer every refusal in the browser with the same page: “Zugang verweigert / Access denied. The punchout could not be started. Please contact your procurement team.” The page deliberately does not name the cause, so check each of these:
| Cause | Fix |
|---|---|
| The Shop ID in the launch URL is wrong, or the shop is inactive | Copy the launch URL from the Embed tab; switch Shop active on |
The username or password is wrong, or the buyer credential is disabled or has the wrong Credential domain (OCI for the OCI launch, IDS for the IDS Connect launch). Craftsman software sends its Benutzername and Passwort, or its Kundennummer when the Benutzername is empty. |
Check the credential on the Buyers tab. For OCI, check whether the buyer system sends parameter names other than USERNAME and PASSWORD (Advanced settings on the General tab). |
OCI: the catalog configuration fills FUNCTION, or the buyer system sends no valid return address. IDS Connect: the craftsman software sends no valid return address, or asks for a function punchout.dev does not support. |
Leave FUNCTION empty and check the catalog or connection settings in the buyer system |
| The return host is not under Allowed return hosts | Add it on the General tab |
| The launch request is too large | Check the catalog configuration in the buyer system |
Craftsman software that does not ask for a web page gets a short JSON error instead of this page when the shop is unknown, the request is too large or the function is not supported.
A launch says “Punchout not enabled”
Section titled “A launch says “Punchout not enabled””The organisation is on the Sandbox plan. The Sandbox refuses every launch from a real buyer system and lets only the portal’s test punchouts through. The refusal looks different for each kind of launch:
| Launch | What the buyer sees |
|---|---|
| Hosted OCI launch, IDS Connect launch | A page “Punchout nicht freigeschaltet / Punchout not enabled. This shop is not enabled for productive punchout yet.” |
| Direct OCI launch at the shop | The panel: “Punchout is not enabled for this shop yet. Please contact the supplier.” |
| cXML | The buyer system reports Supplier not enabled for productive punchout |
Fix: choose a paid plan under Settings → Billing. The next launch goes through. See Plans and Sandbox.
cXML: the buyer system reports an error
Section titled “cXML: the buyer system reports an error”When a cXML punchout cannot start, the buyer system shows a short message. The messages are generic on purpose:
| Message | Meaning | Fix |
|---|---|---|
Unknown tenant or credentials |
The Shop ID in the setup URL is wrong, or the shop is inactive | Copy the cXML PunchOutSetupRequest URL from the Embed tab; switch Shop active on |
Authentication failed |
The login failed: credential domain, identity and shared secret do not exactly match an enabled credential on the Buyers tab | Compare the three values with the credential, or rotate its secret and enter the new one in the buyer system |
Invalid PunchOutSetupRequest |
The request could not be read or is too large, or its return address is malformed or not allowed by the shop | Add the buyer system’s host under Allowed return hosts on the General tab, or ask the buyer admin to check the return address |
Request too large |
The buyer system’s request is too large | Ask the buyer admin to check what the buyer system sends |
Supplier not enabled for productive punchout |
The Sandbox refuses the launch | See above |
Auto-login: the buyer is not signed in
Section titled “Auto-login: the buyer is not signed in”| Cause | Fix |
|---|---|
| Auto-login is off on the Auto-login tab, or the buyer credential has no Shop customer reference | Switch auto-login on and fill in the reference on the Buyers tab |
| The Auto-login tab shows “No signing key is configured.” | There is no key to paste, so auto-login cannot be set up |
| The launch was a direct OCI launch or a test punchout | Auto-login needs a hosted launch: the OCI launch URL, cXML or IDS Connect |
| The plugin refused the token | Look up the reason word in the shop’s log, see Auto-login |
| The buyer lands on a 404 page, because the Login path on the Auto-login tab does not match the plugin’s route | Set the Login path to the plugin’s route, see the platform page |
In the plugin, Enable auto-login is off, or Shop ID or Public key lines is empty (reason disabled or not_configured) |
Fill in the plugin’s settings, or switch auto-login off on the portal’s Auto-login tab |
The daily budget is used up
Section titled “The daily budget is used up”Each shop has a Daily budget for reading carts, cart detection included. The plan sets it, per shop and UTC day. Once it is used up, punchout.dev reads no more carts for that shop until the next UTC day. In a punchout the panel then shows “Analysis failed.”, in setup mode “Detection failed.”, both with Retry.
| Cause | Fix |
|---|---|
| The shop has used its daily budget | Wait for the next UTC day, or move to a plan with a larger budget. The Usage tab shows Daily budget as used of available. |
| The shop’s Sandbox period has ended, so its budget is zero. The portal shows “Sandbox ended” for the shop. | Choose a paid plan under Settings → Billing |
The setup link does not work
Section titled “The setup link does not work”| Message | Cause | Fix |
|---|---|---|
| “The setup link has expired.” | The link is past its validity (60 minutes by default), was already used, was revoked, or the shop is inactive | Create a new link on the Setup tab |
| No setup panel in a new tab | The link is kept only in the browser tab it was opened in | Open the cart in the same tab, or open the link again |
| “No cart was found on this page. Open the cart page with 2–3 items.” | The page has no cart the detection could read | Open the cart page with products in it |
| “The cart could not be detected reliably. Please contact support.” | The automatic detection found no cart area it could confirm | Click Mark the cart myself and click the line items |
| “There is nothing to confirm any more. Please detect the cart again.” | The detection result is gone | Click Detect cart again |
| “Detection failed.” | The daily budget is used up, the shop’s Sandbox period has ended, or a temporary failure occurred | Retry, see The daily budget is used up |
The portal refuses to create a link for an inactive shop: “This shop is inactive. Activate it under General, then the setup link works.” See Cart detection.
“Your plan allows … active connections”
Section titled ““Your plan allows … active connections””Creating or enabling a buyer credential is refused, and the portal says: “Your plan allows {allowed} active connections and {used} are already active. Add a connection or disable one of them.”
One enabled buyer credential is one connection, counted across all shops of the organisation. The limit is checked only when you create an enabled credential or enable a disabled one; disabling, rotating, editing and deleting always work. Fix: disable a credential you no longer need, book Additional connections under Settings → Billing, or change the plan.
The test punchout does not start
Section titled “The test punchout does not start”| Message | Fix |
|---|---|
| “Add {host} to the allowed return hosts under General — otherwise our test receiver is not allowed to take the cart.” | Add the host named in the message under Allowed return hosts |
| “This shop’s sandbox has ended. The Standard plan carries on.” | Choose a paid plan under Settings → Billing |
| “This shop is inactive. Activate it under General, then the setup link works.” | Switch Shop active on |
| “Only owners and admins can start a test.” | Ask an owner or admin, see Team |
| “The test has expired.” | A test run is valid for 60 minutes. Click Test again. |
punchout.dev · hello@punchout.dev