# Cart detection

How punchout.dev finds the element on your cart page that holds the line items, using the plugin marker, a one-time setup link or a cart you mark yourself.

URL: https://punchout.dev/docs/getting-started/cart-detection/

This page explains the cart container, the one-time setup link that finds and checks it, and what to do when detection needs help.

## What the cart container is

The cart container is the element on your cart page that holds the line items. When a buyer opens the cart during a punchout, punchout.dev reads the items from that element. With a known container, the rest of the page, such as the account bar or the address, stays out of the reading.

Which part of the cart page punchout.dev reads:

| Order | What the shop has | What is read |
| --- | --- | --- |
| 1 | The plugin marker: an element with the attribute `data-punchout-cart` | That element |
| 2 | A **Container selector** on the **Cart** tab | That element. If it is not on the page, no cart is read |
| 3 | Neither | The cart page as a whole |

The marker takes precedence over a container selector, so a selector left over from before a plugin was installed cannot get in the way.

## The ways a container becomes known

| Way | When it fits | **Source** on the **Cart** tab |
| --- | --- | --- |
| Shop plugin | Shopware, WooCommerce or Magento with the punchout.dev plugin. The plugin marks the cart itself | `plugin` |
| Setup link, preset | Your shop runs one of those platforms without the plugin and keeps the platform's cart markup | `preset:<name>` |
| Setup link, detected | punchout.dev finds the container on your page by itself | `detected` |
| Mark it yourself | Detection found the items but could not confirm a container | **Picked by hand** |
| Set by hand | You type a CSS selector on the **Cart** tab | `manual` (counts as unverified) |

With a plugin there is nothing to detect. A setup link still works as a self-test: the panel says "Shop plugin detected", and confirming completes the checklist step. Without a plugin, you can set the marker yourself by adding the attribute `data-punchout-cart` to the element in your cart template that holds the line items.

## Create a setup link

1. Open the shop's **Setup** tab. Under **Cart detected**, click **Create setup link**.
2. **Shop path** is where the link lands, for example `/checkout/cart`. The field starts with the shop's landing path; empty means the home page.
3. **Valid for**: 30 minutes, 60 minutes (the default) or 2 hours.
4. Click **Create link**. The portal shows the link only once. Copy it or click **Open in the shop**.

The link opens the shop path on your shop's first allowed origin. It works once: confirming a detection uses it up. **Revoke link** cancels it, and you can replace an expired or revoked link with a new one at any time. While the link is pending, the portal shows "Waiting for the confirmation in the shop" and updates itself when you confirm.

Only owners and admins can create setup links, and only for an active shop (**General** tab → **Shop active**).

## In the shop

The setup link works only in the browser tab it opened in, and it disappears from the address bar. Stay in that tab, because a new tab or window does not know the link. Until you confirm, the panel shows **Setup** on every page of the tab. The cart page must be on one of the shop's allowed origins.

1. Put 2 or 3 different products in the cart and open the cart page.
2. Click **Detect cart**. If your cart fills in after the page has loaded, as the WooCommerce block cart does, the panel waits until the cart has finished loading.
3. The panel shows "Cart detected: 3 items" and the source (**Shop plugin**, **Preset**, **Detected automatically** or **Picked by hand**). It outlines the container on the page and lists the items it read.
4. If the items are right, click **Yes, that's it**. The panel shows "Setup complete" and "The setup link has now been used up." If not, click **No**, change the cart and try again.

The panel appears in German when the page's language is German or, on a page that declares no language, when the browser's language is. Otherwise it appears in English. If the URL does not look like a cart page, the panel warns you but lets you continue, because some shops use their own cart URLs.

In setup mode, punchout.dev reads the page only when you click **Detect cart** or **Check this area**, only while the link is valid, and never as part of a punchout. On a page with the plugin marker, it reads only the marked cart.

## How detection decides

With the plugin marker on the page, punchout.dev uses the marked cart. Otherwise it first tries the known cart layouts of your shop's platform, so set **General** tab → **Shop platform** before you start. If none of them fits, it looks for the container on the page itself. It offers you a container only after checking it on your page.

Automatic detection uses the shop's daily budget ([Plans and Sandbox](https://punchout.dev/docs/account/plans-and-sandbox/)). When the budget is spent, the panel shows "Detection failed." with **Retry**.

## Mark the cart yourself

When automatic detection cannot find the container, the panel offers **Mark the cart myself**. The first panel also shows this option as a link, except on a page with the plugin marker.

1. A transparent layer covers the page. The shop's links and buttons do not react while it is there.
2. Click the area that holds the cart items. **Esc** cancels.
3. The panel shows the element and its **Selector**. **One level up** and **One level down** move to the surrounding or inner element.
4. Click **Check this area**. punchout.dev checks your area the same way it checks one it found itself.

The panel refuses some choices at once: the whole page, an element inside an overlay or drawer cart, and an element it cannot describe in a stable way.

Mark the cart on the cart page itself. A cart drawer or mini cart that opens over another page holds a real cart, but it does not exist on the cart page a buyer punches out from.

## What is stored

Confirming fills three fields on the shop's **Cart** tab: **Container selector**, **Source** and **Verified**. With a plugin, the container selector stays as it was, and only the source and the time change.

## Messages in the panel

| Message | Cause | What to do |
| --- | --- | --- |
| "No cart was found on this page. Open the cart page with 2–3 items." | No line items on the page | Open the cart page with items, then **Retry** |
| "The cart could not be detected reliably. Please contact support." | Items were found, but no container could be confirmed | **Mark the cart myself** |
| "This area could not be confirmed." | Your marked area could not be confirmed | Follow the hint below it |
| "There is nothing to confirm any more. Please detect the cart again." | The detection result is no longer available | **Retry** runs detection again |
| "The setup link has expired." | Link expired, revoked or already used | Create a new link in the portal |
| "Detection failed." | The shop's daily budget is spent, or a temporary error occurred | **Retry** later |

Hints after a marked area fails:

| The hint starts with | Meaning | What to do |
| --- | --- | --- |
| "The area occurs more than once" | The area matches more than one place on the page | **One level up** |
| "The area covers almost the whole page" | Too large | **One level down** |
| "Overlay/drawer cart" | Part of a drawer or modal | Mark the cart on the cart page itself |
| "The area cannot be described stably" | The element has no name that stays the same between page views | Change the level |
| "The area was not found" | The area is no longer on the page | Try again |
| "No items found" | The items are not inside the area | Mark the list of items |

## Detect again later

- **Setup** tab → **Cart detected** → **Detect again** creates a new setup link. Do this after a theme change.
- The **Usage** tab warns "The cart is no longer being found" when, over the last 7 days, punchouts found nothing to read on a cart page at least 3 times and that happened more often than a cart was read. **Detect the cart again** leads to the setup link.
- On the **Cart** tab, **Set the selector by hand** stores a container selector of your own. It counts as unverified and reopens the checklist step. **Clear selector** removes it, and punchout.dev reads the whole cart page again.