OCI, SAP's Open Catalog Interface, is the punchout protocol of SAP SRM, SAP ERP and S/4HANA buyers and of several European procurement systems. Where cXML exchanges XML documents, OCI uses plain web forms: the buyer's system opens the supplier's catalog with a handful of parameters, and the supplier returns the cart as a form of indexed NEW_ITEM fields posted to a HOOK_URL. This page lists those parameters and fields, with samples, and says which of them PunchRelay reads and sends. For the protocol choice, see cXML vs OCI, practically; for the cXML side, the cXML message reference.
OCI 5.0 is OCI 4.0 plus additions for SAP's own catalog products (catalog data replication, item hierarchies). SAP's 5.0 specification states that a 5.0 catalog must also be 4.0 compliant, and the cart round trip below is the 4.0 one, which is what PunchRelay implements.
Opening the catalog: the setup parameters
HOOK_URL=https://srm.example.de/sap/bc/bsp/sap/bbp_oci/return.htm
USERNAME=EXAMPLE_PURCH_01
PASSWORD=the-password-you-issued
OCI_VERSION=4.0
returntarget=_top
The buyer's SAP system calls the supplier's catalog URL with these parameters, as a query string or as a POSTed form, from the user's browser. PunchRelay accepts both.
| Parameter | What it is | PunchRelay |
|---|---|---|
HOOK_URL | Where the cart goes back. Required; the session cannot end without it. | Required. Checked before the credentials. |
USERNAME, PASSWORD | The credentials the supplier issued to this buyer. OCI leaves their names to the catalog; these two are the usual ones. | Checked against the connection; the password is masked in logs. |
OCI_VERSION | The OCI version the buyer's system speaks, for example 4.0. | Read and recorded with the session. |
returntarget | The browser frame the cart form should post into, for example _top or _parent, when the catalog opens inside a frame. | Used as the form's target when the buyer sends it. |
OPI_VERSION, http_content_charset | Version of SAP's Open Partner Interface, and the character set the buyer expects the cart in. | Not read. The cart is sent as UTF-8. |
In the catalog, the buyer sees the Shopify B2B catalog and contract prices of the company and location the connection belongs to.
PunchRelay connects your Shopify B2B store to your buyers' procurement systems: contract prices go out in the punchout catalog, and purchase orders come back to your inbox for review.
Returning the cart: the NEW_ITEM form
<form method="post" action="{HOOK_URL}" target="_top">
<input type="hidden" name="NEW_ITEM-DESCRIPTION[1]" value="Cable ties 200 mm · Black, bag of 100">
<input type="hidden" name="NEW_ITEM-MATNR[1]" value="">
<input type="hidden" name="NEW_ITEM-VENDORMAT[1]" value="CT-200-BK-100">
<input type="hidden" name="NEW_ITEM-QUANTITY[1]" value="12">
<input type="hidden" name="NEW_ITEM-UNIT[1]" value="BG">
<input type="hidden" name="NEW_ITEM-PRICE[1]" value="6.90">
<input type="hidden" name="NEW_ITEM-CURRENCY[1]" value="EUR">
<input type="hidden" name="NEW_ITEM-MATGROUP[1]" value="39121700">
<input type="hidden" name="NEW_ITEM-MANUFACTMAT[1]" value="KB-200-S">
<input type="hidden" name="NEW_ITEM-LEADTIME[1]" value="3">
<input type="hidden" name="NEW_ITEM-DESCRIPTION[2]" value="Cable tie mounts · Self-adhesive, pack of 50">
<input type="hidden" name="NEW_ITEM-VENDORMAT[2]" value="CTM-25-50">
<!-- … the same fields for line 2 … -->
</form>When the user transfers the cart, the supplier's page posts a form to the HOOK_URL through the user's browser. Each line of the cart is a set of fields named NEW_ITEM-<FIELD>[n], where n is the line number starting at 1. The buyer's system turns the lines into a shopping cart or purchase requisition for approval. Nothing is ordered at this point.
The NEW_ITEM fields PunchRelay sends
| Field | Meaning in OCI | What PunchRelay puts in it |
|---|---|---|
DESCRIPTION | Short text of the item | Product title and variant title |
VENDORMAT | The supplier's part number | The variant's SKU, or its ID when the SKU is empty |
MATNR | The buyer's own material number, if the item exists in their material master | Empty, unless you enter the buyer's material number for that product |
QUANTITY | Ordered quantity | Whole number |
UNIT | Unit of measure as an ISO code | The product's UN/CEFACT unit code, EA when none is set |
PRICE, CURRENCY | Net price per unit and its ISO currency | The buyer's contract price from Shopify B2B, with a decimal point |
MATGROUP | Material group used for account assignment and approval routing | The product's UNSPSC code (8 or 10 digits), or one you set per connection; empty when neither exists |
MANUFACTMAT | Manufacturer part number | The product's MPN, when set |
LEADTIME | Delivery time in days | The product's lead time, when set |
CUST_FIELD1 to CUST_FIELD5 | Free fields the buyer's SAP team maps to their own data | Values you set per connection, when the buyer asks for them |
The OCI specification defines more fields, among them long text (LONGTEXT_n:132[]), price unit (PRICEUNIT), the supplier's product ID for later lookups (EXT_PRODUCT_ID), vendor number (VENDOR), contract and quote references, and attachments. PunchRelay does not fill these. If the buyer's field mapping depends on one of them, tell us before enablement starts.
The specification also describes background functions that call the catalog without the user: DETAIL to display an item, VALIDATE to recheck price and availability, and BACKGROUND_SEARCH to search from inside SAP. PunchRelay supports the interactive round trip (open the catalog, return the cart), not these functions.
Errors when the catalog opens
Unlike cXML, OCI has no status document. The catalog answers the setup call with an ordinary web page and an HTTP status, and the user sees that page in the frame or window where the catalog would have opened.
- 400.
HOOK_URLis missing or is not an absolute https URL. PunchRelay checks it before the credentials. - 401, "Sign-in failed".
USERNAMEorPASSWORDdoes not match an enabled connection. An empty password never signs in. - 500. A temporary failure on PunchRelay's side; the user can open the catalog again.
Once the cart form has been posted, OCI gives the catalog no acknowledgment. Whether the buyer's system accepted every line shows up in their shopping cart, not on the supplier's side, so acceptance testing with the buyer's SAP team covers the transfer end to end: units, prices, material groups and any custom fields their mapping reads.
After the cart: the purchase order
OCI ends with the cart. Once the requisition is approved, the purchase order reaches the supplier through a separate channel that the buyer chooses: a cXML OrderRequest (often through SAP Business Network), EDI, or email. Agree on that channel with the buyer before go-live, because it decides how orders reach your team. Our OCI and SAP page covers the commercial side of an OCI connection, and how punchout works the full round trip.
What PunchRelay supports
In short: SAP OCI 4.0 catalog sessions opened with HOOK_URL, USERNAME, PASSWORD, OCI_VERSION and returntarget, by GET or POST; and the cart returned as NEW_ITEM fields (DESCRIPTION, MATNR, VENDORMAT, QUANTITY, UNIT, PRICE, CURRENCY, MATGROUP, and MANUFACTMAT, LEADTIME and CUST_FIELD1–5 when set), with UNSPSC codes of 8 or 10 digits and UN/CEFACT Recommendation 20 units. Material numbers, units, UNSPSC codes and custom fields can be set per connection for the products a buyer orders.