Punchout Documentation

1. Introduction to Punchout

Punchout is an e-procurement integration protocol that connects buyer procurement systems with supplier e-commerce catalogs. It allows users to "punch out" from their procurement application to a supplier's website, browse products, add items to a shopping cart, and then "punch in" back to their procurement system with the shopping cart data for purchase order creation and processing.

This documentation is designed to provide comprehensive information about punchout functionality to different stakeholders:

• Sales teams: Understanding what punchout is and its business benefits to effectively communicate with customers
• Support staff: Troubleshooting common issues and understanding the technical flow to assist customers
• Developers: Implementing, configuring, and customizing punchout functionality

2. Punchout Concepts and Standards

2.1 What is Punchout?

Punchout is a procurement method that allows buyers to access and shop a supplier's catalog from within their procurement system. The term "punch out" describes the process of a user exiting (or "punching out" from) their company's procurement application to shop on a supplier's website and then returning (or "punching in") with their shopping cart contents.

2.2 cXML Overview

Commerce eXtensible Markup Language (cXML) is the most common protocol used for punchout integration. cXML is a standard used by many e-procurement systems.

cXML defines:

• XML message formats for communication between procurement systems and supplier websites
• Authentication mechanisms for secure communication
• Structured formats for transmitting product, pricing, and order information

cXML is based on XML (eXtensible Markup Language) and uses HTTP as its transport protocol. The punchout process involves exchanging several types of cXML documents:

2.3 Benefits of Punchout

For Buyers:

• Access to real-time product information, pricing, and availability
• Streamlined procurement processes with automated data transfer
• Reduced data entry errors and improved accuracy
• Control over procurement spending through approval workflows
• Consolidated purchasing from multiple suppliers through a single system

For Suppliers:

• Increased sales through simplified buyer access
• Control over catalog presentation and content
• Ability to show customer-specific pricing and product assortments
• Opportunities for upselling and cross-selling
• Integration with large enterprise customers without EDI investment

2.4 Standard Punchout Flow

The standard punchout flow consists of the following steps:

1. Authentication and Session Creation:
   • The procurement system sends a PunchOutSetupRequest to the supplier's system
   • The request contains authentication credentials and user information
   • The supplier's system validates the credentials and creates a unique session
2. Redirection to Supplier Website:
   • The supplier's system returns a PunchOutSetupResponse with a URL
   • The user's browser is redirected to the supplier's website
   • The user is automatically authenticated on the supplier's site
3. Shopping Experience:
   • The user browses products and adds items to their cart on the supplier's site
   • The supplier's site may display customer-specific pricing and products
4. Cart Transfer:
   • User clicks a "Complete " or similar button
   • The supplier's system generates a PunchOutOrderMessage with cart details
   • Cart data is transmitted back to the procurement system via browser form POST
5. Order Processing:
   • The procurement system creates a requisition from the cart data
   • The requisition goes through standard approval workflows
   • Upon approval, a purchase order is created and sent to the supplier

3. XML Message Formats

3.1 PunchOutSetupRequest

The PunchOutSetupRequest is sent from the procurement system to initiate a punchout session:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML payloadID="[unique ID]" timestamp="YYYY-MM-DDThh:mm:ssZ">
    <Header>
        <From>
            <Credential domain="[buyer domain]">
                <Identity>[buyer identity]</Identity>
            </Credential>
        </From>
        <To>
            <Credential domain="[supplier domain]">
                <Identity>[supplier identity]</Identity>
            </Credential>
        </To>
        <Sender>
            <Credential domain="[buyer domain]">
                <Identity>[buyer identity]</Identity>
                <SharedSecret>[shared secret]</SharedSecret>
            </Credential>
            <UserAgent>[procurement system name]</UserAgent>
        </Sender>
    </Header>
    <Request deploymentMode="[production/test]">
        <PunchOutSetupRequest operation="create">
            <BuyerCookie>[buyer session ID]</BuyerCookie>
            <Extrinsic name="User">[username]</Extrinsic>
            <Extrinsic name="UniqueUsername">[unique username]</Extrinsic>
            <Extrinsic name="Department">[department]</Extrinsic>
            <BrowserFormPost>
                <URL>[return URL]</URL>
            </BrowserFormPost>
            <Contact>
                <Name xml:lang="en">[user name]</Name>
                <Email>[user email]</Email>
            </Contact>
            <SupplierSetup>
                <URL>[supplier website URL]</URL>
            </SupplierSetup>
            <ShipTo>
                <Address>
                    <Name xml:lang="en">[shipping name]</Name>
                    <PostalAddress>
                        <Street>[street address]</Street>
                        <City>[city]</City>
                        <State>[state]</State>
                        <PostalCode>[postal code]</PostalCode>
                        <Country isoCountryCode="US">United States</Country>
                    </PostalAddress>
                </Address>
            </ShipTo>
        </PunchOutSetupRequest>
    </Request>
</cXML>

3.2 PunchOutSetupResponse

The PunchOutSetupResponse is sent from the supplier system in response to a setup request:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML payloadID="[unique ID]" timestamp="YYYY-MM-DDThh:mm:ssZ">
    <Response>
        <Status code="200" text="OK">
            <!-- Success -->
        </Status>
        <PunchOutSetupResponse>
            <StartPage>
                <URL>https://supplier.com/punchout?token=abc123</URL>
            </StartPage>
        </PunchOutSetupResponse>
    </Response>
</cXML>

Error response example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML payloadID="[unique ID]" timestamp="YYYY-MM-DDThh:mm:ssZ">
    <Response>
        <Status code="401" text="Unauthorized">
            <!-- Authentication failure -->
            Invalid credentials
        </Status>
    </Response>
</cXML>

3.3 PunchOutOrderMessage

The PunchOutOrderMessage contains cart data sent back to the procurement system:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML payloadID="[unique ID]" timestamp="YYYY-MM-DDThh:mm:ssZ">
    <Header>
        <From>
            <Credential domain="[supplier domain]">
                <Identity>[supplier identity]</Identity>
            </Credential>
        </From>
        <To>
            <Credential domain="[buyer domain]">
                <Identity>[buyer identity]</Identity>
            </Credential>
        </To>
        <Sender>
            <Credential domain="[supplier domain]">
                <Identity>[supplier identity]</Identity>
                <SharedSecret>[shared secret]</SharedSecret>
            </Credential>
            <UserAgent>Kodaris Commerce</UserAgent>
        </Sender>
    </Header>
    <Message>
        <PunchOutOrderMessage>
            <BuyerCookie>[buyer session ID]</BuyerCookie>
            <PunchOutOrderMessageHeader operationAllowed="create">
                <Total>
                    <Money currency="USD">123.45</Money>
                </Total>
            </PunchOutOrderMessageHeader>
            <ItemIn quantity="2">
                <ItemID>
                    <SupplierPartID>ABC123</SupplierPartID>
                    <SupplierPartAuxiliaryID>987ZYX</SupplierPartAuxiliaryID>
                </ItemID>
                <ItemDetail>
                    <UnitPrice>
                        <Money currency="USD">45.67</Money>
                    </UnitPrice>
                    <Description xml:lang="en">Widget A</Description>
                    <UnitOfMeasure>EA</UnitOfMeasure>
                    <Classification domain="UNSPSC">12345678</Classification>
                    <ManufacturerPartID>MFG123</ManufacturerPartID>
                    <ManufacturerName>Acme Corp</ManufacturerName>
                </ItemDetail>
            </ItemIn>
            <!-- Additional items -->
        </PunchOutOrderMessage>
    </Message>
</cXML>

3.4 PunchOutOrderRequest

The PunchOutOrderRequest contains purchase order information sent to the supplier:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML payloadID="[unique ID]" timestamp="YYYY-MM-DDThh:mm:ssZ">
    <Header>
        <From>
            <Credential domain="[buyer domain]">
                <Identity>[buyer identity]</Identity>
            </Credential>
        </From>
        <To>
            <Credential domain="[supplier domain]">
                <Identity>[supplier identity]</Identity>
            </Credential>
        </To>
        <Sender>
            <Credential domain="[buyer domain]">
                <Identity>[buyer identity]</Identity>
                <SharedSecret>[shared secret]</SharedSecret>
            </Credential>
            <UserAgent>[procurement system name]</UserAgent>
        </Sender>
    </Header>
    <Request deploymentMode="[production/test]">
        <OrderRequest>
            <OrderRequestHeader orderID="PO12345" orderDate="YYYY-MM-DD" type="regular">
                <Total>
                    <Money currency="USD">123.45</Money>
                </Total>
                <ShipTo>
                    <Address addressID="ShipTo123">
                        <Name xml:lang="en">[shipping name]</Name>
                        <PostalAddress>
                            <Street>[street address]</Street>
                            <City>[city]</City>
                            <State>[state]</State>
                            <PostalCode>[postal code]</PostalCode>
                            <Country isoCountryCode="US">United States</Country>
                        </PostalAddress>
                    </Address>
                </ShipTo>
                <BillTo>
                    <Address addressID="BillTo123">
                        <Name xml:lang="en">[billing name]</Name>
                        <PostalAddress>
                            <Street>[street address]</Street>
                            <City>[city]</City>
                            <State>[state]</State>
                            <PostalCode>[postal code]</PostalCode>
                            <Country isoCountryCode="US">United States</Country>
                        </PostalAddress>
                    </Address>
                </BillTo>
            </OrderRequestHeader>
            <ItemOut quantity="2" lineNumber="1">
                <ItemID>
                    <SupplierPartID>ABC123</SupplierPartID>
                </ItemID>
                <ItemDetail>
                    <UnitPrice>
                        <Money currency="USD">45.67</Money>
                    </UnitPrice>
                    <Description xml:lang="en">Widget A</Description>
                    <UnitOfMeasure>EA</UnitOfMeasure>
                </ItemDetail>
            </ItemOut>
            <!-- Additional items -->
        </OrderRequest>
    </Request>
</cXML>

4. Troubleshooting

Common Issues and Solutions

↑ Back to Top