PunchOut integration specification for custom stores

1. Setup in PunchOut Rocket

E-commerce site

Endpoint paths are appended to the Site URL as they are, so they must start with /. Example: Site URL https://your-store.example.com + /api/punchout/clone → https://your-store.example.com/api/punchout/clone.

Purchase orders (section 6) and predefined carts come with the Premium plan, included in the free trial: your plan enables them on the site, and the end customer page then shows the Orders and Predefined Carts sections. Order confirmations and ship notices (sections 7–8) also need the OC & ASN add-on.

End customer

Each buyer company is an end customer of your site. Besides its protocol credentials (cXML identities and shared secret, or OCI username and password), these fields involve your store:

The rest of the site and end customer pages works as for the other platforms: see the documentation.

2. Clone endpoint

Default path: /api/punchout/clone. Called when a buyer opens your store from the procurement system. Your store creates (or reuses) a user cloned from username, bound to this PunchOut session, and returns an SSO URL that logs that user in (section 3).

Request body

quantity and price are strings: convert them before use.

Request: create, with a selected item

{
  "username": "buyer123",
  "api_key": "site-api-key-abc",
  "session_token": "sess-012345",
  "operation": "create",
  "end_customer_id": 2,
  "gateway_base_url": "https://middleware.example.com",
  "selected_item": {
    "supplier_part_id": "X-100",
    "supplier_part_auxiliary_id": "19853"
  }
}

Request: edit, with the cart to restore

{
  "username": "buyer123",
  "api_key": "site-api-key-abc",
  "session_token": "sess-67890",
  "operation": "edit",
  "end_customer_id": 2,
  "gateway_base_url": "https://middleware.example.com",
  "cart_items": [
    {"sku": "ABC-001", "product_id": "19852", "quantity": "2", "price": "15.95",
     "description": "Example description", "currency": "EUR"},
    {"sku": "XYZ-002", "product_id": "19854", "quantity": "1", "price": "249.00",
     "description": "Another example description", "currency": "EUR"}
  ]
}

Success response

HTTP 2xx

HTTP 200
{
  "status": "success",
  "sso_url": "https://your-store.example.com/punchout/sso?token=eyJ..."
}

sso_url is the only field read: it is required and must be an absolute http:// or https:// URL. PunchOut Rocket sends the buyer’s browser there (through the procurement system for cXML, directly for OCI).

Error responses

Any non-2xx status, or a response without a valid sso_url, fails the PunchOut: the buyer gets an error in the procurement system. Your response (status and body) is saved in the PunchOut session log, so explain the reason in the message.

4. Cart transfer (auto-post form)

For a PunchOut user, the checkout button must not start your checkout: it sends the cart to PunchOut Rocket instead. Your store returns an HTML page that submits a hidden form automatically, ideally with a loader.

• URL: {gateway_base_url}/start-sso-checkout (gateway_base_url from the clone request)
• Method: POST, application/x-www-form-urlencoded (a normal browser form post)
• No api_key: the session is identified by session_token and end_customer_id.

i starts at 0 and has no gaps: PunchOut Rocket stops reading at the first missing index. Remember to HTML-escape the values.

Example page returned at checkout

<!doctype html>
<html>
<body>
<p>Sending your cart to your procurement system…</p>
<form id="punchout_repost" method="post" action="https://middleware.example.com/start-sso-checkout">
  <input type="hidden" name="session_token" value="sess-012345"/>
  <input type="hidden" name="end_customer_id" value="2"/>
  <input type="hidden" name="products[0][sku]" value="ABC-001"/>
  <input type="hidden" name="products[0][product_id]" value="19852"/>
  <input type="hidden" name="products[0][description]" value="Example description"/>
  <input type="hidden" name="products[0][quantity]" value="2"/>
  <input type="hidden" name="products[0][price]" value="15.95"/>
  <input type="hidden" name="products[0][currency]" value="EUR"/>
  <input type="hidden" name="products[0][unit_of_measure]" value="EA"/>
  <input type="hidden" name="products[0][manufacturer_name]" value="3M"/>
  <input type="hidden" name="products[0][category_ids]" value="1145,3398"/>
  <input type="hidden" name="products[1][sku]" value="XYZ-002"/>
  <input type="hidden" name="products[1][product_id]" value="19854"/>
  <input type="hidden" name="products[1][description]" value="Another example description"/>
  <input type="hidden" name="products[1][quantity]" value="4"/>
  <input type="hidden" name="products[1][price]" value="10.90"/>
  <input type="hidden" name="products[1][currency]" value="EUR"/>
  <input type="hidden" name="products[1][manufacturer_name]" value="DEWALT"/>
  <input type="hidden" name="products[1][category_ids]" value="2146"/>
</form>
<script>document.getElementById('punchout_repost').submit();</script>
</body>
</html>

PunchOut Rocket then sends the cart to the procurement system and ends the session. A session accepts one cart only:

7. Order status endpoint

Default path: /api/punchout/order-status. Called only for end customers with “Send order status updates” enabled, for the orders created through section 6: every hour for 60 days from the order, and right away after a notification (section 8). Requires the OC & ASN add-on. From the answer PunchOut Rocket sends the buyer’s procurement system:

• an order confirmation (cXML ConfirmationRequest), once, when the order is accepted or cancelled;
• a ship notice (cXML ShipNoticeRequest) for every new shipment of a confirmed order.

PunchOut Rocket remembers what it sent: always answer with the current state of the order, and PunchOut Rocket works out what is new.

Request: order_id is the one your create order endpoint returned

{"api_key": "site-api-key-abc", "order_id": "100045"}

Success response

HTTP 200

HTTP 200
{
  "status": "success",
  "order_status": "shipped",
  "items": ["5501", "5502"],
  "quantities": [
    {"order_item_id": "5501", "quantity": 2},
    {"order_item_id": "5502", "quantity": 1}
  ],
  "shipments": [
    {
      "id": "SH-1",
      "shipped_at": "2026-11-12T09:30:00+01:00",
      "carrier": "UPS",
      "tracking": "1Z999AA10123456784",
      "items": [{"order_item_id": "5501", "quantity": 2}]
    }
  ]
}

The confirmation is sent once, the first time the order is processing, shipped or delivered:

• it accepts the whole order when every PO line is on it in full;
• otherwise it accepts each line for the quantity the order holds and rejects the rest (removed items, reduced quantities). A quantity raised above the PO is confirmed at the PO quantity;
• if no line is left at all, nothing is sent: use cancelled to reject the order.

Later item changes are not confirmed again: edit the order before accepting it.

Report a shipment only once it has left. Changes made to a shipment after it was notified are not sent again. If the procurement system refuses a confirmation or ship notice, PunchOut Rocket sends it again at the next check, and nothing after it is sent until it is accepted.

9. Go-live checklist

1. Configure the site (section 1) and enter the same API key in your store.
2. Create an end customer and set its “E-commerce User to Clone”.
3. Click “Update from e-commerce” in its Category Mapping and map the categories; set a Default UNSPSC.
4. Test a PunchOut with the cXML test form in the admin panel: create, then edit with a cart, then send the cart back.
5. For purchase orders (Premium plan): send a test OrderRequest and check the order in your store.
6. For status updates (OC & ASN add-on): enable “Send order status updates” on the end customer, move the test order through your states and check that the buyer’s system receives the confirmation and the ship notices.

Remember:

• PunchOut users must not complete a checkout on your store: their cart goes back to the procurement system (section 4), and the order arrives later through section 6.
• Orders received through section 6 are already approved by the buyer’s procurement system: they do not need an online payment.

Need a test buyer or a review of your implementation? Talk to our developers, or let us build it with Go-Live Assist.