> For the complete documentation index, see [llms.txt](https://docs.unimarket.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unimarket.com/documentation/punchout/erp-punchout-to-unimarket-technical-information.md).

# ERP Punchout to Unimarket (Technical Information)

The **Punchout (Roundtrip) process** is a standardized method for a user to leave their internal ERP system, shop within the Unimarket eMarketplace, and return a populated shopping cart to their ERP for approval and requisitioning.

{% hint style="info" %}
For a business-level overview of why and how to set up a marketplace punchout, see [eMarketplace Punch-out (ERP to Unimarket)](/documentation/punchout/emarketplace-punchout-erp-to-unimarket.md).
{% endhint %}

## The Three-Phase Punchout Process

The entire interaction happens through three primary cXML messages:

![Punchout process diagram](https://help.unimarket.com/hc/article_attachments/53678241026969)

### 1. Punchout Setup Request (ERP → Unimarket)

The ERP initiates a session by sending an HTTPS POST request to Unimarket. This message establishes the user's identity and provides a "return address" for the cart.

**Key attributes:**

* **Community ID:** Identifies the specific Unimarket customer community.
* **System Credentials:** The `Identity` and `SharedSecret` for authentication.
* **Buyer Username:** The specific user shopping in the session.
* **BrowserFormPost:** The URL where Unimarket must send the final shopping cart data.

**Example request:**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.020/cXML.dtd">
<cXML payloadID="payloadId" timestamp="2009-11-06T13:50:13+13:00" version="1.2" xml:lang="en">
    <Header>
        <From>
            <Credential domain="unimarket-id">
                <Identity>cb897379-12df-4a5f-ab87-05709517f44b</Identity>
            </Credential>
        </From>
        <To>
            <Credential domain="unimarket-id">
                <Identity/>
            </Credential>
        </To>
        <Sender>
            <Credential domain="unimarket-user">
                <Identity>5cd5ed4c-09c3-4c51-871d-3cde84e09556</Identity>
                <SharedSecret>SuperSecretPasswordHere</SharedSecret>
            </Credential>
            <UserAgent>Unimarket Testing System.</UserAgent>
        </Sender>
    </Header>
    <Request deploymentMode="production">
        <PunchOutSetupRequest operation="create">
            <BuyerCookie>NA</BuyerCookie>
            <Extrinsic name="User">TestPunchoutUser</Extrinsic>
            <BrowserFormPost>
                <URL>https://your.procurement.system.com</URL>
            </BrowserFormPost>
        </PunchOutSetupRequest>
    </Request>
</cXML>
```

### 2. Punchout Setup Response (Unimarket → ERP)

Once Unimarket authenticates the request, it creates a unique session and responds immediately.

* **The StartPage URL:** This is the most critical element of the response. The ERP must take this URL and open it in the user's web browser. This URL automatically logs the user into the Unimarket home page without requiring a second login.

**Example response:**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<cXML payloadID="c7c69828-ab1a-4ab0-a7a1-f77a199d9c3d" timestamp="2020-05-01T13:42:04.601+12:00" version="1.2.038" xml:lang="en">
    <Response>
        <Status code="200" text="success"/>
        <PunchOutSetupResponse>
            <StartPage>
                <URL>https://miketest.unimarket-demo.com/app/home?cid=c7c69828-ab1a-4ab0-a7a1-f77a199d9c3d</URL>
            </StartPage>
        </PunchOutSetupResponse>
    </Response>
</cXML>
```

### 3. Punchout Order Message (Unimarket → ERP)

After the user selects their items and clicks "Checkout" within Unimarket, the system redirects the user's browser back to the ERP.

* **Mechanism:** Unimarket performs a POST to the `BrowserFormPost` URL provided in Phase 1.
* **Data Payload:** The cart details are included in a parameter named `cxml-urlencoded`.
* **Requirement:** The ERP system must URL-decode this parameter to retrieve the valid cXML, which contains line-item details like SKU, quantity, price, and UNSPSC codes.

**Example Punchout Order Message (URL-encoded):**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.021/cXML.dtd">
<cXML payloadID="c7c69828-ab1a-4ab0-a7a1-f77a199d9c3d" timestamp="2020-05-01T13:42:52.536+12:00" version="1.2.021" xml:lang="en">
    <Header>
        <From>
            <Credential domain="unimarket-id">
                <Identity>cb897379-12df-4a5f-ab87-05709517f44b</Identity>
            </Credential>
        </From>
        <To>
            <Credential domain="unimarket-id">
                <Identity/>
            </Credential>
        </To>
        <Sender>
            <Credential domain="unimarket-id">
                <Identity>cb897379-12df-4a5f-ab87-05709517f44b</Identity>
                <SharedSecret>SuperSecretPasswordHere</SharedSecret>
            </Credential>
            <UserAgent>UMKT</UserAgent>
        </Sender>
    </Header>
    <Message>
        <PunchOutOrderMessage>
            <BuyerCookie>NA</BuyerCookie>
            <PunchOutOrderMessageHeader operationAllowed="create">
                <Total>
                    <Money currency="NZD">4.00</Money>
                </Total>
                <Shipping>
                    <Money currency="NZD">20.00</Money>
                    <Description xml:lang="en">$20.00 per order</Description>
                </Shipping>
            </PunchOutOrderMessageHeader>
            <ItemIn quantity="4">
                <ItemID>
                    <SupplierPartID>1000010</SupplierPartID>
                    <SupplierPartAuxiliaryID/>
                    <IdReference domain="unimarketProductId" identifier="ca1be02d-60f2-47ce-9090-1add34657995"/>
                </ItemID>
                <ItemDetail>
                    <UnitPrice>
                        <Money currency="NZD">1.00</Money>
                    </UnitPrice>
                    <Description xml:lang="en">Product Code 10</Description>
                    <UnitOfMeasure>EA</UnitOfMeasure>
                    <Classification domain="UNSPSC">44000000</Classification>
                </ItemDetail>
                <SupplierID domain="DUNS"/>
            </ItemIn>
        </PunchOutOrderMessage>
    </Message>
</cXML>
```

**Example Punchout Order Message (decoded to XML):**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.021/cXML.dtd">
<cXML payloadID="c7c69828-ab1a-4ab0-a7a1-f77a199d9c3d" timestamp="2020-05-01T13:42:52.536+12:00" version="1.2.021" xml:lang="en">
    <Header>
        <From>
            <Credential domain="unimarket-id">
                <Identity>cb897379-12df-4a5f-ab87-05709517f44b</Identity>
            </Credential>
        </From>
        <To>
            <Credential domain="unimarket-id">
                <Identity/>
            </Credential>
        </To>
        <Sender>
            <Credential domain="unimarket-id">
                <Identity>cb897379-12df-4a5f-ab87-05709517f44b</Identity>
                <SharedSecret>SuperSecretPasswordHere</SharedSecret>
            </Credential>
            <UserAgent>UMKT</UserAgent>
        </Sender>
    </Header>
    <Message>
        <PunchOutOrderMessage>
            <BuyerCookie>NA</BuyerCookie>
            <PunchOutOrderMessageHeader operationAllowed="create">
                <Total>
                    <Money currency="NZD">4.00</Money>
                </Total>
                <Shipping>
                    <Money currency="NZD">20.00</Money>
                    <Description xml:lang="en">$20.00 per order</Description>
                </Shipping>
            </PunchOutOrderMessageHeader>
            <ItemIn quantity="4">
                <ItemID>
                    <SupplierPartID>1000010</SupplierPartID>
                    <SupplierPartAuxiliaryID/>
                    <IdReference domain="unimarketProductId" identifier="ca1be02d-60f2-47ce-9090-1add34657995"/>
                </ItemID>
                <ItemDetail>
                    <UnitPrice>
                        <Money currency="NZD">1.00</Money>
                    </UnitPrice>
                    <Description xml:lang="en">Product Code 10</Description>
                    <UnitOfMeasure>EA</UnitOfMeasure>
                    <Classification domain="UNSPSC">44000000</Classification>
                </ItemDetail>
                <SupplierID domain="DUNS"/>
            </ItemIn>
        </PunchOutOrderMessage>
    </Message>
</cXML>
```

## Technical Implementation Details

### Setup Request Configuration

The request must be sent as an HTTPS POST to the community-specific web service URL (e.g., `https://miketest.unimarket-demo.com/ws`).

{% hint style="info" %}
**Example setup logic:** If the `From` identity is `cb897379...`, the Unimarket system recognizes the specific tenant and validates the `SharedSecret` against the credentials stored in the community's Integration settings.
{% endhint %}

### The Return Handshake

The return process is "transparent" to the user. When they finish shopping, Unimarket bundles the `PunchOutOrderMessage` (containing the cart) and sends it via the user's browser back to the ERP. This allows the ERP to "grab" the items and populate a draft requisition automatically.

## Troubleshooting Common Issues

* **401 Unauthorized:** Usually caused by a mismatch in the `SharedSecret` or a missing `unimarket-id` in the header.
* **StartPage Not Opening:** Ensure the ERP is configured to handle the `PunchOutSetupResponse` synchronously and can redirect the browser session to the provided URL.
* **Empty Cart on Return:** Check that the `BuyerCookie` in the Order Message matches the cookie sent in the initial Setup Request.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.unimarket.com/documentation/punchout/erp-punchout-to-unimarket-technical-information.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.