Setup Request vs cart return: understanding the difference

In a PunchOut integration, two cXML messages do the bulk of the work: the PunchOutSetupRequest and the PunchOutOrderMessage. They are often confused in the early stages of a project, even though they have nothing in common.

This article clarifies who sends them, when, and what is actually at stake.

The PunchOutSetupRequest: opening the session

The PunchOutSetupRequest is sent by the procurement system to the supplier’s storefront, at the very start of the flow.

Its role: to announce “a user from X wants to enter your storefront to shop, here’s who they are and where their cart should be sent back”.

Concretely, it contains:

• the buyer’s technical credentials (Credential blocks)
• information about the user (name, email, sometimes role)
• a return URL (BrowserFormPost)
• optionally a currency, a language, a country

The storefront does not yet receive a cart. It receives a session-opening request, full stop.

Its response - the PunchOutSetupResponse - contains a start URL. The procurement system then redirects the user to that URL, and the browsable session begins.

The PunchOutOrderMessage: returning the cart

The PunchOutOrderMessage is sent by the storefront to the procurement system, at the end of the flow, when the user submits their cart.

Its role: to transmit “here are the items, quantities, prices and codes the user selected; import this into your approval process”.

It contains:

• the original session identity (context recall)
• the list of items (ItemIn), with quantity, price, description
• the product codes expected by the buyer (internal codes, UNSPSC, supplier SKUs)
• the units of measure
• taxes and other contractual data

This is the message that, once on the buyer side, feeds the internal cart for approval.

Why the confusion is dangerous

A developer starting a PunchOut project may be tempted to handle everything in a single flow: “I receive the SetupRequest, I authenticate, I handle the cart, I send it back”.

Except:

• the SetupRequest arrives before the user has seen a single product;
• the PunchOutOrderMessage is built later, when the cart exists;
• the session must be preserved between the two, sometimes for several minutes or more.

Typical bugs come from this confusion:

• session lost between entry and exit (cookie misconfigured, lifetime too short);
• return URL forgotten or badly stored (cart ready but nowhere to send it);
• mapping applied at the wrong stage (on the SetupRequest instead of the PunchOutOrderMessage).

How Gatebold handles it

In Gatebold, these two messages are distinct events inside an explicit session model:

• the PunchOutSetupRequest opens a session, journaled and observable;
• the session carries the context (buyer, user, return URL) all the way to the cart;
• the PunchOutOrderMessage is built using the buyer’s mapping, validated, journaled.

If something goes wrong, you see at which stage - not a vague indistinct error.

This is exactly what the PunchOut feature page covers.

In short

Message	Direction	When	Contains
PunchOutSetupRequest	Buyer → Storefront	Start	Identity, return URL
PunchOutOrderMessage	Storefront → Buyer	End (cart submit)	Items, prices, codes

Two messages, two directions, two moments. Confusing them means hours of debugging. Telling them apart cleanly is the foundation of a PunchOut integration that survives in production.

If you have a concrete case in mind, let’s talk.