Getting Started with Punchout on Kodaris

A guide for distributors setting up punchout for their customers.

---

What is Punchout?

Punchout is a way for your customers to shop on your website directly from their procurement system (like Ariba, Coupa, or Jaggaer).

Here's what happens:

1. Your customer logs into their procurement system (where they manage all their purchasing)
2. They click a link to "punch out" to your website
3. They're automatically logged in and can browse and add items to their cart
4. When they're done, they click "Checkout with Punchout"
5. Their cart is sent back to their procurement system for approval
6. Once approved, the order is automatically sent to you

Why do buyers use punchout?

Large organizations (hotels, school districts, hospitals, property management companies) often require all purchases to go through their procurement system for:

• Budget approval workflows
• Spending controls and reporting
• Centralized purchasing across multiple locations

If your customer asks about "punchout," "cXML," or connecting to their "procurement system," this is what they're referring to.

---

Before You Start: Understand Your Customer's Setup

Before setting up punchout, you need to understand how your customer is set up in their procurement system. This determines how we configure things on the Kodaris side.

What is a Supplier Connection?

In your customer's procurement system, they create a Supplier Connection for your company. This is where they store the credentials (Identity and Shared Secret) that authenticate orders to your system.

Think of it like a login - one Supplier Connection = one set of credentials.

Two Common Scenarios

Scenario 1: One Supplier Connection = One Customer (Simple)

This is the straightforward setup:

• Your buyer has ONE Supplier Connection for your company
• That maps to ONE customer number in your ERP
• All their delivery locations are ship-tos under that one customer

Procurement System              Your ERP
------------------              --------
Supplier Connection  -------->  Customer #1001
  - Address A                     - ShipTo A
  - Address B                     - ShipTo B
  - Address C                     - ShipTo C

This works perfectly with standard punchout setup.

---

Scenario 2: One Supplier Connection = Multiple Customers (Parent/Child)

This is more complex and common with:

• School districts (district office + multiple schools)
• Property management companies (corporate + multiple properties)
• Hotel chains (management company + individual hotels)

In this case:

• Your buyer has ONE Supplier Connection (one set of credentials)
• But they order for MULTIPLE locations that are SEPARATE customer numbers in your ERP

Procurement System              Your ERP
------------------              --------
                                Customer #1001 (School A)
Supplier Connection  -------->  Customer #1002 (School B)
(One Secret Key)                Customer #1003 (School C)
                                Customer #1004 (School D)

How we handle this:

• We create a "parent" company in Kodaris (just for punchout authentication)
• Each actual ERP customer becomes a "child" company
• A script automatically routes orders to the correct child based on information in the punchout request

Important: You need to find out which scenario applies BEFORE setting up punchout. Ask your customer:

• "Do all your locations order under one account number with us?"
• "Or do different locations have different customer numbers?"

---

Ship-To Address Mapping

Your customer's procurement system uses its own address codes (like "ADDR-001", "ADDR-002"). These don't match the ship-to codes in your ERP.

You need to map these.

What to do:

1. Ask your customer for a list of their delivery addresses and IDs - They should be able to export this from their procurement system
2. Match each address to your ERP ship-to code - You know which of their locations maps to which ship-to in your system
3. Enter the mapping in Kodaris - You can do this yourself via import or the admin portal. We'll provide documentation or walk you through it if needed

Example mapping:

Procurement Address ID	ERP Ship-To Code	Location
PROP-101	SHIPTO-A	Main Office
PROP-102	SHIPTO-B	Warehouse
PROP-103	SHIPTO-C	Branch Office

Without this mapping, orders won't know where to ship.

---

The Setup Process

Step 1: Contact Kodaris

Let us know that you want to set up punchout. We will:

• Make sure the required scripts are in place
• Provide you with documentation
• Answer any initial questions

Step 2: Talk to Your Customer and Their Procurement System

Find out:

• Which scenario applies? (Single customer or parent/child?)
• What information do they need from you? (See "What They'll Ask For" below)
• What are their delivery address IDs? (For ship-to mapping)

Step 3: Schedule a Kickoff Call (If Needed)

For complex setups, it helps to get everyone on a call:

• You (the distributor)
• Your customer (the buyer)
• The procurement system representative
• Kodaris support (if technical expertise is needed)

This ensures everyone understands the setup and avoids back-and-forth later.

Step 4: Create the Punchout User in Kodaris

Follow the Punchout Customer Creation guide to:

1. Navigate to the company
2. Add a punchout customer
3. Assign appropriate roles
4. Get the secret key from Developer Fields

Step 5: Provide Credentials to the Procurement System

They will need the following information to configure their side:

Field	What to Provide
Sender Identity	The punchout username you created (e.g., punchout-114729@yourdomain.com)
Sender Shared Secret	The key from Developer Fields in Kodaris
Setup Request URL	https://[your-kodaris-url]/api/user/punchOut/setup
Order Request URL	https://[your-kodaris-url]/api/user/punchOut/order

They may also ask for From/To Domain and Identity values. See the Punchout Customer Creation guide for options if you don't know these.

Step 6: Testing

Once the procurement system has configured their side:

1. Have your customer test "punching out" to your site
2. They should be automatically logged in
3. Have them add items to cart and complete the punchout checkout
4. Verify the order appears in your system

Step 7: Troubleshooting

If errors occur during testing:

• Note the exact error message
• Contact Kodaris - we can review the cXML messages and configuration
• Common issues include incorrect credentials, unmapped addresses, or missing configuration

---

What They'll Ask For

When the procurement system sets up the Supplier Connection, they'll typically ask you for:

Required:

• Sender Identity (the punchout username)
• Sender Shared Secret (the key)
• Setup Request URL
• Order Request URL

They may also ask for:

• From Domain (use "NetworkID" if unknown)
• From Identity (use customer code if unknown)
• To Domain (use "NetworkID" if unknown)
• To Identity (use your company identifier if unknown)

Note: We only validate the Sender Identity and Shared Secret. The From/To values are passed through but not strictly validated, so defaults work fine if you don't have specific values.

---

Quick Reference

Punchout URLs

Purpose	URL
Setup Request	https://[your-kodaris-url]/api/user/punchOut/setup
Order Request	https://[your-kodaris-url]/api/user/punchOut/order

Key Terms

Term	Meaning
Punchout	Shopping on your site from within a procurement system
Procurement System	Software buyers use to manage purchasing (Ariba, Coupa, Jaggaer, etc.)
Supplier Connection	The configuration in the procurement system that stores your credentials
cXML	The XML format used to communicate between systems
Setup Request	The message that authenticates and gets a shopping URL
Order Request	The message that submits the final approved order
Shared Secret	The password/key that authenticates requests

---

Common Questions

Q: My customer mentioned punchout but I don't know what procurement system they use. A: Ask them directly. Common ones include Ariba, Coupa, Jaggaer, SAP, Oracle, and Yardi. The setup process is similar regardless of which system they use.

Q: Do I need to do anything special on my website? A: No. Kodaris handles punchout automatically. The customer shops normally - they just start from their procurement system and their cart goes back there instead of checking out directly.

Q: What if my customer has multiple locations? A: Find out if those locations are separate customer numbers in your ERP. If yes, you'll need the parent/child setup (Scenario 2). If they're all ship-tos under one customer, it's the simple setup (Scenario 1).

Q: How long does setup typically take? A: For simple setups, a few days once everyone has the right information. Complex parent/child setups may take longer due to additional configuration and testing.

Q: What if we run into problems during testing? A: Contact Kodaris. We can review the cXML messages being sent and help identify the issue. Punchout setup can involve some back-and-forth - that's normal.

---

Need Help?

• Contact Kodaris Support for setup assistance and troubleshooting
• Request a call if you need help understanding your customer's requirements
• We can join kickoff calls with you and the procurement system if technical expertise is needed

Getting punchout working can be a process, but once it's set up, it runs automatically. We're here to help you through the implementation.