> 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/emarketplace-punchout-erp-to-unimarket.md).

# eMarketplace Punch-out (ERP to Unimarket)

Unimarket can be configured as a centralized **eMarketplace** that sits on top of your existing ERP system (such as Workday, PeopleSoft, Oracle, or TechnologyOne). In this setup, your ERP system treats Unimarket as a single **Punchout (Roundtrip)** destination.

## Why Use a Marketplace Punchout?

The traditional method of integrating individual suppliers into an ERP is costly and inefficient. Each new supplier requires a separate firewall configuration, Punchout setup, and PO/Invoice integration.

**Benefits of the Marketplace approach:**

* **Single Integration:** Access all your suppliers through one connection to Unimarket.
* **Lower Maintenance:** Adding or changing suppliers requires no further technical integration on the ERP side.
* **Enhanced Security:** Minimizes the number of "holes" in your corporate firewall by consolidating third-party traffic.

## The Punchout Process

The integration adheres to the **cXML standard**, making it compatible with any ERP that supports cXML. Download a [process overview](https://help.unimarket.com/hc/en-us/article_attachments/45852236062745) of the punch-out process.

{% hint style="info" %}
For the full request/response message walkthrough and additional XML examples, see [ERP Punchout to Unimarket (Technical Information)](/documentation/punchout/erp-punchout-to-unimarket-technical-information.md).
{% endhint %}

#### 1. Punchout Setup Request

When a user clicks the Unimarket link in your ERP, the ERP sends a `PunchOutSetupRequest`. This message authenticates the session and identifies the user.

**Key XML requirements:**

* **Sender Credentials:** Contains the `Identity` and `SharedSecret` for authentication.
* **Extrinsics:** Must include the user's email, first name, and last name to determine which Unimarket cart to use.
* **BrowserFormPost:** The URL where Unimarket will post the cart data back to the ERP.

#### 2. Punchout Cart Return (PunchOutOrderMessage)

Once the user finishes shopping in Unimarket, the marketplace sends a `PunchOutOrderMessage` back to the ERP. This "returns" the items to the ERP requisition.

**Key data returned:**

* **ItemDetail:** Includes unit price, description, unit of measure, and UNSPSC classification.
* **SupplierID:** Identifies which marketplace supplier the item belongs to.
* **BuyerCookie:** Matches the return message to the original setup request session.

## Setup and Testing

To successfully establish the "handshake" between your ERP and Unimarket:

1. **Retrieve Credentials:** Log in to Unimarket and navigate to **Edit Community > Integration** to find your specific credentials.
2. **Configure ERP:** Set the Identity, Shared Secret, and Punchout URL in your ERP's supplier maintenance module.
3. **Test the Connection:** Use the [Unimarket Roundtrip Tester](https://akl-office.unimarket.co.nz:7443/roundtrip-tester/) to simulate a request and verify the XML structure.

## Technical Resources

For full schema details and DTD definitions, refer to the following:

* [cXML User Guide](https://help.unimarket.com/hc/en-us/article_attachments/45852214985113): For deep-dives into message structures.
* **cXML.dtd:** The official document type definition for message validation, available in the downloads below.

### Sample Punchout Setup 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="2020-01-06T13:50:13+13:00" version="1.2" xml:lang="en">
    <Header>
        <From>
            <Credential domain="DUNS">
                <!-- 1. ENTER VALUE HERE used to get tenant for authentication based on Domain options for DUNS, Network ID or others -->
                <Identity> 8 digit ID or other based on Domain </Identity>
            </Credential>
        </From>
        <To>
            <Credential domain="unimarket-code">
                <Identity> 8 digit ID or other based on Domain </Identity>
            </Credential>
        </To>
        <Sender>
            <Credential domain="unimarket-user">
                <!-- 2. ENTER VALUE HERE used to get username for authentication -->
                <Identity>9520969d-e16b-46db-9d03-859874d883f6</Identity>
                <!-- 3. ENTER VALUE HERE used to get password for authentication -->
                <SharedSecret>password1</SharedSecret>
            </Credential>
            <UserAgent>Initiating System or ERP</UserAgent>
        </Sender>
    </Header>
    <Request deploymentMode="production">
        <PunchOutSetupRequest operation="create">
            <BuyerCookie>Long UUID created for each session</BuyerCookie>
            <!-- 4. ENTER VALUE HERE unimarket username (to determine whose cart should be used) -->
            <Extrinsic name="User">john.doe@school.edu</Extrinsic>
            <Extrinsic name="email">john.doe@school.edu</Extrinsic>
            <Extrinsic name="FirstName">John</Extrinsic>
            <Extrinsic name="LastName">Doe</Extrinsic>
            <BrowserFormPost>
                <URL>http://admin.unimarket-demo.com/roundtrip-tester-module/receive-cxml-cart.jsp</URL>
            </BrowserFormPost>
        </PunchOutSetupRequest>
    </Request>
</cXML>
```

### Sample Punchout Cart Return (PunchOutOrderMessage)

```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="2020-01-06T13:50:13+13:00" version="1.2" xml:lang="en">
    <Header>
        <From>
            <Credential domain="DUNS">
                <!-- 1. ENTER VALUE HERE used to get tenant for authentication based on Domain options for DUNS, Network ID or others -->
                <Identity> 8 digit ID or other based on Domain </Identity>
            </Credential>
        </From>
        <To>
            <Credential domain="unimarket-code">
                <Identity> 8 digit ID or other based on Domain </Identity>
            </Credential>
        </To>
        <Sender>
            <Credential domain="unimarket-user">
                <!-- 2. ENTER VALUE HERE used to get username for authentication -->
                <Identity>9520969d-e16b-46db-9d03-859874d883f6</Identity>
                <!-- 3. ENTER VALUE HERE used to get password for authentication -->
                <SharedSecret>password1</SharedSecret>
            </Credential>
            <UserAgent>Initiating System or ERP</UserAgent>
        </Sender>
    </Header>
    <Message>
        <PunchOutOrderMessage>
            <BuyerCookie>a05918eb-556e-4269-a612-dffac9b8d30d</BuyerCookie>
            <PunchOutOrderMessageHeader operationAllowed="create">
                <Total>
                    <Money currency="USD">32.29</Money>
                </Total>
                <Shipping>
                    <Money currency="USD">0.00</Money>
                    <Description xml:lang="en">Standard Shipping</Description>
                </Shipping>
            </PunchOutOrderMessageHeader>
            <ItemIn quantity="1">
                <ItemID>
                    <SupplierPartID>LS1234</SupplierPartID>
                    <SupplierPartAuxiliaryID/>
                    <IdReference domain="unimarketProductId" identifier="Long UUID number"/>
                </ItemID>
                <ItemDetail>
                    <UnitPrice>
                        <Money currency="USD">32.29</Money>
                    </UnitPrice>
                    <Description xml:lang="en">Product Text Description</Description>
                    <UnitOfMeasure>EA</UnitOfMeasure>
                    <Classification domain="UNSPSC">49161506</Classification>
                </ItemDetail>
                <SupplierID domain="SupplierNumber">BSHC</SupplierID>
            </ItemIn>
        </PunchOutOrderMessage>
    </Message>
</cXML>
```

### Downloads

* [cXMLUsersGuide.pdf](https://help.unimarket.com/hc/en-us/article_attachments/45852214985113) (7 MB)
* [cXML.dtd](https://help.unimarket.com/hc/en-us/article_attachments/45852230028057) (200 KB)
* [Unimarket\_Marketplace\_Process.pdf](https://help.unimarket.com/hc/en-us/article_attachments/45852236062745) (40 KB)


---

# 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/emarketplace-punchout-erp-to-unimarket.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.