Partner Sends Setup Request

Your system sends a request to SCX with credentials and customer information. SCX authenticates the request and creates a shopping session.

• REST
• cXML
• OCI

POST /api/punchout/setup
X-Api-Key: scx_your_api_key_here
Content-Type: application/json

{
  "customerId": "YOUR-CUSTOMER-ID",
  "serviceCenterId": "1961",
  "returnUrl": "https://your-app.com/cart-return",
  "operation": "create",                        // create | edit | inspect (default: create)
  "existingCartItems": [ ... ]                  // required for edit/inspect
}

POST /api/cxml
Content-Type: text/xml

<?xml version="1.0" encoding="UTF-8"?>
<cXML payloadID="unique-id" timestamp="...">
  <Header>
    <From>
      <Credential domain="NetworkID">
        <Identity>Your Company</Identity>
      </Credential>
    </From>
    <To>
      <Credential domain="NetworkID">
        <Identity>SCX</Identity>
      </Credential>
    </To>
    <Sender>
      <Credential domain="NetworkID">
        <Identity>Your Company</Identity>
        <SharedSecret>your-api-key</SharedSecret>
      </Credential>
    </Sender>
  </Header>
  <Request>
    <PunchOutSetupRequest operation="create">
      <BuyerCookie>unique-session-id</BuyerCookie>
      <BrowserFormPost>
        <URL>https://your-app.com/cart-return</URL>
      </BrowserFormPost>
      <Extrinsic name="CustomerID">YOUR-CUSTOMER-ID</Extrinsic>
      <Extrinsic name="ServiceCenterID">1961</Extrinsic>
    </PunchOutSetupRequest>
  </Request>
</cXML>

POST /api/oci
Content-Type: application/x-www-form-urlencoded

USERNAME=your-username
PASSWORD=your-api-key
HOOK_URL=https://your-app.com/cart-return
CUSTOMER_ID=YOUR-CUSTOMER-ID
SERVICE_CENTER_ID=1961
FUNCTION=CREATE

SCX Returns Session URL

SCX creates a session and returns a URL. Your application opens this URL — typically in a modal iframe or a new browser window — so the buyer can browse the catalog.

• REST
• cXML
• OCI

HTTP 200 OK

{
  "success": true,
  "sessionUrl": "https://scx.example.com/shop/abc123token",
  "sessionToken": "abc123token"
}

HTTP 200 OK (application/xml)

<cXML>
  <Response>
    <Status code="200" text="OK">Success</Status>
    <PunchOutSetupResponse>
      <StartPage>
        <URL>https://scx.example.com/shop/abc123token</URL>
      </StartPage>
    </PunchOutSetupResponse>
  </Response>
</cXML>

HTTP 302 Redirect

Location: https://scx.example.com/shop/abc123token

Buyer Browses the Catalog

The buyer sees the Solution Center product catalog filtered to their customer's catalog types and pricing. They browse products, view details, and add items to their cart. The catalog runs inside SCX and is displayed in your application's iframe or window.

Cart is Returned to Your Application

When the buyer submits their cart, SCX sends the cart data back to the returnUrl you provided in the setup request. cXML and OCI return carts via protocol-defined form POSTs. REST integrations choose one of three callback methods on their integration config:

REST callback methods (per-integration setting):

• PostMessage — JavaScript window.postMessage sends cart JSON to the iframe parent, then top-window navigates to returnUrl with a session token
• Redirect — Top-window redirects to {returnUrl}?token={token}; your handler fetches cart via GET /api/punchout/session/{token}
• Post — Hidden HTML form auto-submits the cart JSON to returnUrl as cartJson plus items[N].* fields

cXML and OCI (protocol-defined):

• cXML — Hidden form auto-submits the PunchOutOrderMessage XML to BrowserFormPost URL as field cXML-urlencoded
• OCI — Hidden form auto-submits cart as NEW_ITEM-* fields to HOOK_URL

Cart data structure (JSON):

{
  "items": [
    {
      "productId": "item-guid",
      "sku": "ABC-1234",
      "name": "Premium Ceremonial Product",
      "quantity": 2,
      "unitPrice": 149.99,
      "currency": "USD",
      "unitOfMeasure": "EA",
      "imageUrl": "/images/product.jpg"
    }
  ],
  "subtotal": 299.98,
  "currency": "USD",
  "itemCount": 1
}

Your Application Processes the Cart

Your application receives the cart data and can display it to the user, create a purchase order, or process it however your system requires. You can also query the session endpoint (GET /api/punchout/session/{'{'}token{'}'}) at any time to retrieve the cart data.