What is a PunchOutSetupRequest?

What the setup request does

When a buyer at Bakker Installatie B.V. clicks your tile in the procurement system, the system posts a PunchOutSetupRequest to your endpoint over HTTPS. Your endpoint answers in the same connection with a PunchOutSetupResponse that holds a status and a start URL, and the procurement system sends the buyer's browser to that URL. Every fact on this page comes from the cXML Reference Guide 1.2.071 and its DTD, checked on October 3, 2026, unless a procurement system is named.

The request has three jobs:

Everything else, the user's name, a cost center, a delivery address, a product the buyer already picked, is optional and differs per procurement system.

The document, annotated

This is an edit request: the buyer reopens the cart of 3 lines sent earlier, to change a quantity.

<cXML payloadID="1791032780.2210.55012@procure.bakker.example"
      timestamp="2026-10-03T10:12:40-04:00">
  <Header>
    <From><Credential domain="NetworkId"><Identity>bakker-installatie</Identity></Credential></From>
    <To><Credential domain="NetworkId"><Identity>your-store</Identity></Credential></To>
    <Sender><Credential domain="NetworkId"><Identity>bakker-installatie</Identity>
      <SharedSecret>the-agreed-secret</SharedSecret></Credential></Sender>
  </Header>
  <Request deploymentMode="production">
    <PunchOutSetupRequest operation="edit">
      <BuyerCookie>7QW2M0D41KXA</BuyerCookie>
      <Extrinsic name="UserEmail">j.devries@bakker.example</Extrinsic>
      <BrowserFormPost><URL>https://procure.bakker.example/return</URL></BrowserFormPost>
      <ItemOut quantity="120"><ItemID><SupplierPartID>10482</SupplierPartID>
        <SupplierPartAuxiliaryID>cart-88231</SupplierPartAuxiliaryID></ItemID></ItemOut>
      <!-- two more ItemOut lines: 2 x panelboard, 5 x cable ties -->
    </PunchOutSetupRequest>
  </Request>
</cXML>

The payloadID is unique per document and stays the same if the request is sent again. The timestamp is ISO 8601 with a UTC offset. deploymentMode is test or production, and production is the default when it is absent. The full envelope is explained on cXML PunchOut.

Element by element

The DTD fixes the order of the body: BuyerCookie, then Extrinsic*, BrowserFormPost?, Contact*, SupplierSetup?, ShipTo?, SelectedItem?, ItemOut*. A * means zero or more, a ? zero or one.

The reference says the endpoint can use From to identify the company and Contact and the extrinsics to identify the person, and that buying organizations configure which of those they send. Its advice is to ask each customer what to expect.

Who the user is

What arrives about the person differs per procurement system:

An endpoint that requires UserEmail fails the first buyer whose administrator did not configure it. SAP's guide for suppliers on SAP Business Network adds that required extrinsics lengthen the implementation and should be kept to a minimum. The store therefore opens the session on the company from From alone, and uses the person's data when it is there, for example to give each buyer their own cart.

The BuyerCookie is not a session key

The reference says the BuyerCookie is unique per PunchOut session and changes from create to inspect to edit, and that a store should not use it to track sessions. Two systems bend that:

• Coupa creates one BuyerCookie per user and PunchOut site and never changes it, as described on PunchOut for Coupa.
• Through SAP Business Network, a request from Ariba Buyer 7.0 arrives with a session ID number in place of the value the buyer's system generated.

A store that keys its sessions on the BuyerCookie mixes up two sessions of the same Coupa user. The endpoint creates its own session identifier, stores the BuyerCookie next to it, and returns the cookie only in the cart.

Worked example: rebuilding a cart on edit

The edit request above carries the 3 lines of the original cart. The endpoint matches each SupplierPartAuxiliaryID to the stored cart cart-88231 and rebuilds it at today's contract price:

The original total was 120 x 9.60 + 298.00 + 18.75 = 1,468.75. With the receptacle at 9.85 the rebuilt cart is 1,182.00 + 298.00 + 18.75 = 1,498.75, 30.00 more. The difference shows in the cart the buyer sends back, so it is visible before approval. The reverse, keeping 9.60 because the cart was created at that price, is a rule per buyer agreement and is stored with the session. An endpoint that does not support edit answers 450 Not Implemented, and Coupa, which sends only create and inspect, never asks for it.

What the response has to contain

The reference asks for a start URL that refers to the session state instead of carrying it, because many applications limit URL length. A short identifier such as ?sid=9f2c41d8a07b that works once and expires fast does that, and a copied link then opens nothing.

What this means for your integration

A setup endpoint has to accept documents that differ per procurement system, identify the company without depending on optional fields, keep its own session key and answer with a start URL that signs the buyer in.

We build the endpoint on your existing store, keep the per-buyer rules (credentials, extrinsics, price on edit) in the integration and log every setup request with its response. The whole PunchOut flow, from setup request to invoice, is on the PunchOut hub. Send us a sample setup request from your customer.