Punchout

This page is the reference for the punchout App, for developers who connect a buyer's procurement system (SAP, Ariba, Coupa or a wholesale system speaking IDS) to a storefront. For a walkthrough, start with Connect a procurement system by punchout.

A punchout visit has three legs. The procurement system calls an entry address with its own credentials, the buyer lands signed in on your storefront and fills a cart, and the cart goes back to the procurement system as a hand-back form the buyer's browser submits. The procurement system then approves and orders on its side. The punchout App never creates an order and reserves no stock, and a hand-back sends the cart as it stands: it is a transfer, not a sale. The one exception is an IDS account whose purchase mode lets the buyer check out in the shop: the order is then an ordinary storefront order, and the App only records it. That needs a storefront that offers the checkout exit, which @revenexx/cover does not do yet (as of 2026-10).

Every admin route below is under https://api.revenexx.com/v1/punchout and takes the usual X-Revenexx-Tenant and X-Revenexx-Api-Key headers.

Protocols

What each protocol does not serve:

• OCI serves the shopping call only. DETAIL, VALIDATE, SOURCING, BACKGROUND_SEARCH, DOWNLOADJSON, DETAILADD and QUANTITYCHECK answer 501, and an unknown FUNCTION answers 400. OCI parameter names are read in any casing.
• cXML serves PunchOutSetupRequest with the operations create, edit and inspect. edit and inspect reopen a requisition from the request's lines, and inspect is view-only. source answers cXML Status 450. There is no OrderRequest handling: the purchase order the procurement system later sends does not arrive through this App.
• IDS serves WKE, ADL, AS, WKS, LI and SV. WKS always imports into a new cart. HLS answers 501.

A cart that comes in (cXML edit and inspect, IDS WKS) is priced at your channel's prices, not at the prices the procurement system sent.

Entry addresses

The procurement system calls your storefront host, not the API gateway:

The storefront passes each call through to the App unchanged and writes the answer back byte for byte. It authenticates nothing itself, because the credentials are the App's business. The spec also lists /v1/punchout/entry/… routes. Those are what the storefront forwards to, they need a tenant credential, and a procurement system cannot call them.

The storefront must run a theme built on @revenexx/cover, which carries the entry routes, the sign-in page at /punchout/start and the hand-back page. @revenexx/cover-theme extends it, so a theme on either layer has them. The theme's theme.json must also be allowed to call the capabilities behind them. The cover-theme and custom-theme starting points declare all five:

"permissions": [
  { "capability": "punchout.entry.oci",       "compatible": "^1.0" },
  { "capability": "punchout.entry.cxml",      "compatible": "^1.0" },
  { "capability": "punchout.entry.ids",       "compatible": "^1.0" },
  { "capability": "punchout.sessions.claim",  "compatible": "^1.0" },
  { "capability": "punchout.sessions.return", "compatible": "^1.0" }
]

Two more things have to be true for a buyer to arrive signed in. The Customers setting login_magic_link (Sign in with a mailed link) must be on for the tenant, and not switched off by the buyer's organization. It is off by default. And the buyer must land on /punchout/start, the only page that signs them in, so the tenant's storefront address (below) or the account's own start_page_url must be that page.

A theme deployed with the static runtime adapter has no server, so it can never serve entry. See Theme anatomy for the manifest and Build configuration for the adapter.

The buyer's browser has to accept cookies, because the visit is carried in a cookie.

Tenant settings

Some values are the same for every account, so they are punchout App settings for the tenant rather than account fields. An operator sets them in Cockpit's settings form for the Punchout App, and GET /v1/settings/apps/punchout reads the values in force.

An account can override the first two, with start_page_url and session_ttl_override_minutes. Leave both empty unless one buyer needs something different.

Accounts

/accounts is plain CRUD: GET and POST on /accounts, and GET, PUT and DELETE on /accounts/{id}. One account is one procurement system of one buyer.

A null sent for a switch with a default (secure_oci, auth_strategy, echo_entry_parameters, enabled, unknown_user_policy, purchase_mode) is ignored: a new account takes the default, and an existing one keeps its value. A null on an optional field such as start_page_url clears it.

Secrets are compared in constant time. An account missing the credential its protocol needs is refused as misconfigured.

Who the buyer is

When the buyer arrives, the App decides which contact the visit shops as:

1. The entry call names nobody: the account's fallback_contact_id.
2. The name looks like an email and matches a contact in the account's organization: that contact.
3. Anything else follows unknown_user_policy. fallback shops as the fallback contact, and is refused as misconfigured if none is set. refuse ends the visit as unknown_buyer. create creates a contact from the name, but only when the name looks like an email; otherwise it is refused as unknown_buyer.

OCI user names and IDS customer numbers are rarely email addresses, so most OCI and IDS accounts run on the fallback contact. Set one.

Probe, test and preview

The probe answers {account, entry_probe_status, entry_probe_at, entry_probe_url, entry_probe_detail, passed, cause}. It times out after 5 seconds and follows up to three same-origin redirects.

Enabling is gated on the probe. Setting enabled: true without a passed probe on the current entry address answers 409: punchout account '<code>' cannot be enabled until its entry URL answers. <cause> Probe its entry URL, then enable it. The details carry entry_probe_status and cause. A finding counts only for the entry address it was taken on, so changing code, protocol, start_page_url or the tenant's storefront_url makes it stale, and an account that is already enabled is not re-checked. The gate follows the tenant setting entry_probe_required, which defaults to true.

A test visit is revoked straight away, imports no cart and does not count toward the lockout.

Field mappings

A field mapping is one row that fills one target in one document from one source. /field-mappings is plain CRUD, and a row with account_id: null is the tenant default that every account inherits unless it has its own row for the same target.

A row is unique per account, protocol, document, scope and target. A target the protocol cannot carry is refused with 400 when you write it.

Sources (25): constant, cart, line, product, product_attribute, parent_product, parent_attribute, price, quantity, unit, currency, session, account, contact, organization, business_unit, address, order, media, setting, document, unserved, cxml.payload_id, cxml.supplier_part_auxiliary_id, cxml.field.

Mutators (19): trim, upper, lower, max_length, prefix, suffix, number_format, price_format, strip_tags, html_entity_decode, date_iso8601, unix_timestamp, language_alpha3, base64_encode, value_map, strip_punctuation, unit_uncefact, gtin, raw.

GET /vocabularies lists the App's vocabularies (mapping-sources, mapping-mutators, mapping-scopes, entry-probe-outcome, purchase-modes, among others), and GET /vocabularies/{name} returns one. GET /vocabularies/mapping-sources gives every source with its options. Read them there rather than guessing.

You can extend a document but not reorder it. Elements the standard names keep the standard's order. A cXML Extrinsic is addressed by a key in brackets, Extrinsic[CostCenter], which never reaches the document; it tells two Extrinsic rows apart. Write the element's @name as its own row.

POST /defaults seeds the shipped default mappings and is safe to repeat: rows you edited are left alone, and the answer is {created, existing}.

Hand-back

The storefront calls POST /sessions/{psid}/return when the buyer transfers the cart, and the browser submits the form it describes:

A theme built on @revenexx/cover makes this call, builds the form and signs the buyer out. You call it yourself only in a storefront of your own.

The purchase mode adds three 409 codes to the hand-back, and each leaves the visit open: hand_back_not_offered (the visit's mode is order, so its exit is the checkout), cart_already_ordered (a transfer visit whose cart was ordered) and order_missing (an order_and_transfer visit whose cart has no order yet).

Purchase mode (IDS)

A wholesaler's trade software speaking IDS can let the buyer order in your shop instead of handing the cart back for approval. purchase_mode on the account decides which exit a visit gets, and the visit keeps the mode it opened with, even if you change the account mid-visit. The claim answers it as purchase_mode, so the storefront knows which button to show.

The order is an ordinary order placed through the ordinary checkout for the contact the visit shops as, so the same checks apply as to any other storefront order for that contact. See Give buyer staff the right permissions. A visit that shops as the fallback contact can order only if that contact's role grants orders.create; without it, the buyer can at most request an order.

Purchase modes need punchout 2.5.0. It asks for two new permissions, customers.contacts.permissions and orders.list, so a tenant stays on the previous version, with no purchase_mode and no /ordered, until an admin consents in Cockpit.

POST /sessions/{psid}/ordered takes an empty JSON body {}. psid is the visit's handle, the same one the claim and the hand-back use. The App does not trust the caller: it asks the orders App for the order the visit's cart became, and records it on the visit.

curl -X POST https://api.revenexx.com/v1/punchout/sessions/{psid}/ordered \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "psid": "…",
  "status": "ordered",
  "order_id": "…",
  "order_number": "10023",
  "order_status": "placed",
  "ordered_at": "2026-10-12T09:41:00Z",
  "replayed": false
}

• order_status is pending for an order awaiting the buyer organization's approval and placed otherwise. It is a snapshot taken when the visit closed: read the order itself for its current status. A later decline does not reopen the visit.
• A retry is safe. A visit already closed this way answers the same body with replayed: true.
• Checkout may outlast the visit. A visit that ran out while the buyer paid still closes as ordered if the order was created before it ran out.

@revenexx/cover offers only the hand-back today (as of 2026-10). It does not read purchase_mode or call /ordered, and its starting points do not declare punchout.sessions.ordered. Set order or order_and_transfer only for a theme of your own, built on @revenexx/cover for the entry routes, that reads purchase_mode from the claim, shows the checkout, calls /ordered or /return after it, and lists punchout.sessions.ordered in its theme.json permissions.

/sessions is plain CRUD as well. GET /sessions/{id} reads a visit with its status, purchase_mode and, once ordered, order_id, order_number, order_status and ordered_at.

Refusals and limits

Refused calls during a lockout count toward it, so a procurement system that keeps retrying stays locked out. Account codes are visible in the OCI and cXML entry addresses, so anyone who knows one can trigger the lockout. They cannot get in by doing so.

A wrong credential and an unknown account answer identically, and unknown codes are locked out the same way, so a caller cannot probe for account codes. OCI answers 401 punchout entry refused: the credentials are not valid for this account, cXML answers HTTP 200 carrying Status 401 Sender identity or shared secret is invalid, and IDS answers 401. Test calls don't count toward the lockout.

GET /entry-refusals lists every refused entry: account_code, account_id, protocol, reason, origin (entry or tester), client_ip, occurred_at.

Related

• Channels — a punchout channel that shows only its assigned assortment.
• Organizations and contacts — who a visit shops as.
• API Explorer — every route, under Procurement → Punchout.