How to use this

POST a PunchOutSetupRequest here. This is the only URL your system needs.

A PunchOutSetupResponse with a StartPage URL. Open it in a browser (or an iframe, as most buyer platforms do) and you are in the shop.

<Response>
  <Status code="200" text="OK">operation=create; from=YOURID; ...
      conformant=true; errors=0; advisories=1</Status>
  <PunchOutSetupResponse>
    <StartPage>
      <URL>https://punchoutsandbox.com/shop?session=…</URL>
    </StartPage>
  </PunchOutSetupResponse>
</Response>

Read the Status text. It reports which credentials arrived, whether your BuyerCookie was present, and how many conformance errors and advisories your request had. That is the fastest feedback loop here.

Add items, go to the cart, press Return cart. The sandbox renders a browser form that POSTs a PunchOutOrderMessage to your BrowserFormPost URL — which is how the protocol really works. It is not a server-to-server call, and if your endpoint depends on cookies or blocks framing, that is exactly where it breaks.

What the status codes mean

Sessions last an hour. These are the states you will actually meet while testing, and what each one is telling you.

Two habits worth having: start each test run with a clean cookie jar, and remember a returned cart is single-use — returning it clears it, so a back-button resubmit cannot double your requisition. To test a second return, start a second punchout.

Paste this into a terminal:

curl -s -X POST https://punchoutsandbox.com/punchout/setup \
  -H 'Content-Type: text/xml' \
  --data-binary @- <<'XML'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.071/cXML.dtd">
<cXML payloadID="demo@example.com" timestamp="2026-01-01T00:00:00+00:00">
 <Header>
  <From><Credential domain="NetworkID">
    <Identity>my-company</Identity></Credential></From>
  <To><Credential domain="NetworkID">
    <Identity>YOUR-IDENTITY</Identity></Credential></To>
  <Sender><Credential domain="NetworkID">
    <Identity>my-company</Identity>
    <SharedSecret>YOUR-SECRET</SharedSecret></Credential>
   <UserAgent>curl</UserAgent></Sender>
 </Header>
 <Request deploymentMode="test">
  <PunchOutSetupRequest operation="create">
   <BuyerCookie>my-session-123</BuyerCookie>
   <BrowserFormPost><URL>https://example.com/return</URL></BrowserFormPost>
  </PunchOutSetupRequest>
 </Request>
</cXML>
XML

Open the StartPage URL it returns. To watch the cart come back without building a receiver, point BrowserFormPost/URL at a request-capture service.

Eight products carry a quirk badge. Each reproduces a documented real-world failure, and each is labelled with what goes wrong and on which platform. Add one deliberately and watch what your system does with it.

SAP SRM, ECC and S/4HANA speak OCI, not cXML. There is no handshake — point your external web service straight at this URL and the user's browser arrives with the return address attached.

In SRM: Define External Web Services, with row 1 as the URL above and a second row naming the return-URL parameter HOOK_URL.

FUNCTION=VALIDATE

SRM calls this to re-check a line it already holds — typically when a requisition is built from a template and the price may have moved. QUANTITY comes with the call, so scale pricing is resolved at that quantity:

https://punchoutsandbox.com/oci/setup?FUNCTION=VALIDATE&PRODUCTID=MSC-1001
    &QUANTITY=1     → NEW_ITEM-PRICE[1] = 4.85
    &QUANTITY=100   → NEW_ITEM-PRICE[1] = 3.60

A catalogue that ignores QUANTITY and returns list price is why a requisition rebuilt from a template silently loses its volume discount.

FUNCTION=BACKGROUND_SEARCH

Cross-catalog search. SRM runs this against every catalogue configured for it and merges the hits into one list. You are not being browsed — you are being scraped, once, from the DOM you return.

https://punchoutsandbox.com/oci/setup?FUNCTION=BACKGROUND_SEARCH
    &SEARCHSTRING=paper&HOOK_URL=…

FUNCTION=DETAIL

A pure human drill-down — it returns the product page and no data. Needs PRODUCTID matching an EXT_PRODUCT_ID the catalogue issued; no HOOK_URL required, since nothing is returned.

/validate takes any cXML document and checks it against the real DTDs. It separates errors (the DTD says you are wrong — not a matter of opinion) from advisories (valid, and will still cause you trouble). Useful on its own, without a punchout session.

A punchout ends with a requisition, not an order. What happens next is where most integrations actually break, and where nobody can test: your buyer system turns the cart into a purchase order and sends it to the supplier, and the supplier sends back three documents that your system either ingests silently or drops silently.

Send us the order. POST an OrderRequest to:

Same credentials as the punchout endpoint — your identity in To/Credential/Identity, your secret in Sender/Credential/SharedSecret. Everything that parses is accepted, however non-conformant; a document being wrong is the usual reason for sending it here.

The response puts everything we noticed in the Status text: line count, whether lineNumber was present, whether your header Total reconciles with the sum of the lines. That lands in your own transaction log, which is where you will actually look.

Then send documents back. On the order screen you can generate:

Each is validated against the real DTD and shown to you before it goes anywhere. Sending is a separate, deliberate step: set your cXML inbox in Settings and press send.

One attempt per press, no automatic retries. cXML tells suppliers to retry a transport failure hourly for ten hours. That is right for production and wrong here — you are trying to see the failure, and a retry that eventually succeeds hides the flakiness you came to find.

We will only POST to https on port 443, to a hostname whose every resolved address is public, connecting to the exact address we checked, following no redirects, with a valid certificate. "Take a URL from a stranger and POST to it" is the definition of server-side request forgery, and this sandbox runs inside someone else's AWS account. Settings lists the rules in full.

/validate tells you whether a document is conformant. That is necessary and not sufficient, because cXML imposes almost no length limits — every limit that truncates your data is imposed by the buyer platform on ingestion, and none of them publish it. A perfectly valid cart can arrive with the wrong price on it.

/ingest answers that question instead. Paste a PunchOutOrderMessage (or use your current cart) and it applies what each platform is known to do on receipt:

Each finding is labelled with one of four outcomes: reject loudly, reject vaguely, accept and corrupt, accept and preserve. Only the third should frighten you — a rejection is a bad afternoon, a silent change is a wrong price nobody notices until reconciliation.

Where the numbers come from, and how sure we are. Vendor documentation, support notes and observed behaviour, gathered because no platform publishes a consolidated table — the full working is on the conformance reference. Rules we cannot fully evidence are marked unverified on the page rather than quietly asserted. If you know one of them is wrong, that is the single most useful thing you can tell us.

Everything above assumes a browser somewhere. If you are a script, an agent, or CI, you never need one. Nothing below requires a form, a cookie or a human.

Get credentials.

Returns your identity, shared secret and a map of where each one goes. No password, no confirmation email, no browser.

Authenticate. The same credentials, in headers — or HTTP Basic, with the identity as the username:

Validate, and get the findings as data.

Send the document as the raw body or as {"document": "<cXML…"} — both work. Refusals are honest HTTP: 401 unauthenticated, 422 refused before parsing, 429 quota. That is deliberately unlike the cXML endpoints, which answer 200 with a cXML Status because the spec makes any other reply a transport error that clients retry for ten hours.

The punchout round trip needs no browser either. POST a PunchOutSetupRequest, follow the StartPage URL with a cookie jar, add to the cart, POST to /cart/return, and read the cart out of the cxml-base64 field. A live punchout session is authorisation in itself — the shopper is your employee and you already authenticated for them, so the storefront never asks them to sign up.

/samples serves one valid example of each message this sandbox speaks — PunchOutSetupRequest, PunchOutOrderMessage, ConfirmationRequest, ShipNoticeRequest, InvoiceDetailRequest.

Each is generated by the same builder that produces the real thing, so it cannot drift out of date, and the test suite asserts every one validates against the real DTD.

Worth pulling the ship notice specifically if you are writing an extractor: ItemID is optional there and UnitOfMeasure is not — the reverse of every other item block in cXML, and the usual reason a parser written from the other documents fails on that one. ShipControl is also a sibling of ShipNoticePortion, not inside it: one shipment can cover several orders, so carrier and tracking sit at the request level.

And then the ones designed to break your parser. Each of the samples above agrees with itself — the ship notice despatches exactly what was ordered, in the same unit, at the same price — so an extractor that ignores UnitOfMeasure entirely passes all of them. These do not:

All of them are conformant cXML that a real supplier really sends. The point is not malformed input — the validator covers that — but well-formed input carrying a fact your code may be assuming away.

Found something wrong, or need a case this does not cover? That is worth knowing — the source is here.