How to use PunchOut

commercebuild PunchOut is a billable add-on. Please reach out to us if you would like this feature enabled for your web store.

commercebuild's PunchOut technology can be used to integrate with platforms, such as TradeCentric or Greenwing. However, it is possible that you'd like to leverage our PunchOut technology for another purpose.

In this guide, we'll show how you can enable PunchOut for a specific user group and configure the required API payload so that a user is automatically authenticated and the items they add to their cart are automatically transferred to the service you prefer.

Enabling PunchOut for a User Group

Once PunchOut has been enabled for your web store, navigate to the customer group for which PunchOut will be used by going to Customers > Customer Groups > PunchOut2Go Settings .

• Enable this group for PunchOut2Go - If enabled, this means that any web store user in this group or created in the group can be authenticated through commercebuild PunchOut.
• Site Hash - This hash, which should be a random sequence of characters, is used to authenticate the request. This value will be specified by default and will be unique for the user group.
• Allow All ERP Customers - If enabled, this setting allows the user to be linked to any ERP A/R customer code, which is specified in the initial PunchOut request (see "Sample Params (JSON)" below).
• ERP Customer Codes Allowed - If not all ERP customers are allowed, this input allows you to specify which ERP A/R customer codes will be allowed in the PunchOut request using the specified Site Hash.
• Default Warehouse Codes - When the request is authenticated, the user specified in the request will only be able to access the warehouses specified in this list.

Once you have configured these settings, be sure to click Apply before continuing.

Configuring the Request

This form below will help you simulate your request and test commercebuild PunchOut.

Understanding the Parameters

• Return URL - This is the URL that will receive the list of items, their quantities, their units of measure, and their prices. Your return URL should be structured such that any information needed to identify the customer (such as their ERP A/R customer code) or the cart (such as a cart ID) are parameters within the URL, e.g. https://*.com/{ERP_CUSTOMER_CODE}/{CART_ID]. A sample data payload sent to the return URL can be found below.
• Sample Params (JSON) - The parameters provided are the bare minimum. Removing any parameter will not allow the punchout request to process successfully. Additionally, not all parameters are currently supported. The body.shipping parameter, for example, is not transferred to the system, nor is it posted to the Return URL. On the other hand, the ERP A/R custom.CustomerCode and the custom.SiteHash are utilized, as well as the data.UserEmail.
• Your Web Store Domain - In this input, please put your web store's domain.

CURL Request

The form above simulates a CURL request like the one below. You will need to emulate this request in the programming language used in your integration.

curl 'https://yourwebstore.com/punchout2go/authenticate' \
  -H 'content-type: application/x-www-form-urlencoded' \
  --data-raw 'return_url=https%3A%2F%2Fsupport.commercebuild.com%2F1200%2FfhBSahehGa22' \
  --data-raw 'params={
    "header": {},
    "type": "setuprequest",
    "operation": "create",
    "body": {
    "data": {
        "User": "user_id",
        "UserEmail": "user_email@mailinator.com",
        "UserPrintableName": "FirstName LastName",
        "UserFirstName": "FirstName",
        "UserLastName": "LastName"
        },
        "contact": {
          "data": [],
          "email": "user_email@mailinator.com",
          "name": "FirstName LastName",
          "unique": "user_id"
        },
        "shipping": {},
        "items": []
      },
      "custom": {
        "CustomerCode": "1200",
        "SiteHash": "71b8b87d29f3021131583fd935c140fc9f807b79b81221988c5495e5a8682aca"
      }
    }'

Return URL Payload Example

This is an example of the payload received that we will send to the return URL when a user transfers their cart:

params={"body":{"edit_mode":0,"items":[{"quantity":1,"supplierid":"A1-900\/B","supplierauxid":"129\/demo300v2022\/3546\/A1900B","unitprice":"43.19","currency":"USD","classification":"","uom":"Ea.","description":"Answering Machine","language":"en"}],"total":43.189999999999998,"shipping":0,"shipping_method":"","tax":3.5632000000000001,"tax_description":"","currency":"USD"}}

Receiving the Data

Once a user transfers their cart, the cart data and the user are sent to the Return URL. The return URL should be prepared to intercept this data.

Here is an example in PHP showing how this data could be received:

<?php
// Set content type as JSON
header('Content-Type: application/json');
// Intercept the data
$input = file_get_contents('php://input');
// Decode the URL-encoded string
$data = urldecode($input);
// Decode the JSON data
$json = substr($data, strpos($data, '=') + 1);
// Echo the JSON
echo $json;