OCI punchout: how SAP buyers shop in your catalog

OCI punchout is how an SAP buyer shops in a supplier's web catalog from inside their SAP system. OCI, SAP's Open Catalog Interface, opens the catalog in the user's browser with a return address called HOOK_URL. When the user finishes, the catalog posts the cart back as NEW_ITEM form fields, and SAP turns them into shopping cart items.

This page is for suppliers selling to companies on SAP SRM, SAP ERP or S/4HANA, and for the integrator who connects them. It follows SAP's own OCI specification. For every field and parameter, see the OCI field reference; for punchout in general, how punchout works.

Who uses OCI?

OCI is SAP's protocol. SAP's specification describes it as the way SAP SRM takes in external product catalogs, and SAP's documentation for SAP ERP and S/4HANA describes OCI catalog calls from maintenance and work orders. If your buyer runs another procurement system, ask their IT team whether it uses OCI or cXML before you build anything.

In SAP SRM, the buyer's SAP team enters your catalog in Customizing under Define External Web Services, with its URL and the parameters your catalog expects. In SAP ERP, a maintenance planner can call an external catalog from a maintenance or service order, a task list or a network, and copy materials or services into the order; SAP Help describes how the system then creates a purchase requisition for items set up as non-stock. SAP's Catalog Connectivity Service guide describes S/4HANA 2022 and S/4HANA Cloud Public Edition connecting to a catalog with OCI-based protocols, again with a HOOK_URL as the address the cart returns to. Our procurement systems page lists which protocol each system uses with PunchRelay.

How does an OCI round trip work?

Everything goes through the user's browser. The buyer's SAP system calls your catalog URL with login parameters and a HOOK_URL. The user shops. Your catalog then serves a page with a form of NEW_ITEM fields whose action is the HOOK_URL, and the browser posts it to SAP. In standard OCI no server calls another.

POST https://catalog.example.com/punchout/oci
Content-Type: application/x-www-form-urlencoded

USERNAME=EXAMPLE_PURCH_01
PASSWORD=the-password-you-issued
HOOK_URL=https://srm.example.de/sap/bc/bsp/sap/bbp_oci/return.htm
OCI_VERSION=4.0
http_content_charset=utf-8
returntarget=_top

1. Opening the catalog. SAP sends the parameters stored for your catalog, such as the username and password you issued, plus HOOK_URL, OCI_VERSION, OPI_VERSION, http_content_charset and returntarget. SRM can be set to send them by GET or POST; SAP's standard value is POST.
2. Shopping. The user browses your catalog and builds a cart, usually in a window or frame that SAP opened.
3. Returning the cart. Your last page holds a form with the cart in hidden NEW_ITEM fields. The HOOK_URL goes into the form's action attribute, the character set from http_content_charset into the page's meta tag, and returntarget into the form's target. SAP recommends POST for this form, because GET can run into browser length limits.
4. Back in SAP. SAP creates shopping cart items from the fields. Approval and the purchase order happen in SAP, outside OCI.

<form method="post" action="{HOOK_URL}" target="_top">
  <input type="hidden" name="NEW_ITEM-DESCRIPTION[1]" value="Safety gloves, nitrile, size L">
  <input type="hidden" name="NEW_ITEM-VENDORMAT[1]" value="GL-NIT-L-100">
  <input type="hidden" name="NEW_ITEM-QUANTITY[1]" value="20">
  <input type="hidden" name="NEW_ITEM-UNIT[1]" value="BX">
  <input type="hidden" name="NEW_ITEM-PRICE[1]" value="11.40">
  <input type="hidden" name="NEW_ITEM-CURRENCY[1]" value="EUR">
  <input type="hidden" name="NEW_ITEM-MATGROUP[1]" value="46181504">
</form>

Compared with cXML, the usual OCI round trip has no XML document and no status code in either direction. The cXML punchout guide covers the other protocol, and cXML vs OCI compares the two.

Which OCI version does a supplier need?

Build for OCI 4.0. SAP's 5.0 specification adds catalog data replication into SAP SRM, item hierarchy fields, inbound and outbound handlers, and a way to pass credentials outside the browser, and it states that a 5.0 catalog must also be 4.0 compliant. The browser round trip in both documents is the 4.0 one.

SAP's 4.0 document dates from 2003 and the 5.0 document from 2012. According to the 5.0 specification, the replication part works only for SAP SRM customers who have installed the SAP SRM User Interface Add-On. The buyer's system sends OCI_VERSION with every call, and the specification calls it purely informative: it tells the catalog which fields and processes the SAP side supports. PunchRelay implements the 4.0 round trip.

Which fields carry the cart?

Each cart line is a set of fields named NEW_ITEM-<FIELD>[n], where n is the line number. SAP requires a description or an SAP material number and a quantity on every line, a unit when there is no material number, and a currency when there is a price. All other fields are optional.

• Product numbers have separate fields: MATNR is the buyer's own material number and should be filled only when the catalog knows it, VENDORMAT is your part number, MANUFACTMAT the manufacturer's, and EXT_PRODUCT_ID the catalog's own key for the product.
• DESCRIPTION holds 40 characters. Longer text goes in NEW_ITEM-LONGTEXT_n:132[], which has no length limit.
• UNIT and CURRENCY must be ISO codes maintained in the buyer's SAP system.
• PRICE takes up to 11 digits before the decimal point and 3 after it, with no thousands separators.
• CUST_FIELD1 to CUST_FIELD5 have no fixed meaning. The buyer's SAP team decides what goes in them and reads them on their side.

The OCI field reference lists every field, the parameter table and what PunchRelay puts in each.

Why does OCI return only a cart?

OCI ends when the cart reaches SAP. SAP's specification covers calling the catalog and transferring the item data that SAP needs to create shopping cart items; it defines no purchase order message. The buyer approves the cart in SAP, SAP creates the purchase order, and the order reaches the supplier by some other route.

Agree on that route before go-live. If the buyer's system can send cXML purchase orders, give them a cXML order URL. If it cannot, the order arrives the way that buyer already sends you purchase orders. Either way, the line items should match what you sent in the cart, so keep part numbers and units the same in both places.

How should the password travel?

Ask the buyer to call your catalog with POST. With GET, the username and password sit in the URL, where server logs and browser history keep them. POST is already SAP SRM's standard call method, so the buyer's team usually only has to leave the setting as it is.

The HOOK_URL should be https, since the cart and its prices travel to it. SAP's specification also describes Secure OCI, in which the buyer's system passes username, password and price data in server-to-server calls and only a session ID goes through the browser. A catalog has to support that variant explicitly. If the buyer plans to switch it on, ask the catalog provider first.

What breaks during testing?

Check three things first: a missing or non-https HOOK_URL, credentials that do not match, and units or currencies that are not maintained as ISO codes in the buyer's SAP system. OCI gives the catalog no answer after the cart is posted, so problems with the cart show up only in the buyer's shopping cart.

SAP SRM can keep an application log for each OCI catalog, which the buyer's team reads in transaction SLG1 with the object BBP_OCI. Our punchout errors guide goes through each symptom and what to check.

OCI on Shopify with PunchRelay

PunchRelay is the catalog end of OCI for a Shopify B2B store. The buyer's SAP system opens your catalog through PunchRelay, the user sees the Shopify B2B catalog and prices of their company location, and the cart goes back to SAP as NEW_ITEM fields. Each OCI connection includes a one-time $499 setup by PunchRelay.

What PunchRelay does: it accepts the call by GET or POST, refuses a missing or non-https HOOK_URL and a username and password that do not match, and opens the catalog with a link that works once. It shows the company location's catalog and contract prices (list prices when the location has no catalog) and prices the lines again when the user transfers the cart. The cart goes out as DESCRIPTION, MATNR, VENDORMAT, QUANTITY, UNIT, PRICE, PRICEUNIT, CURRENCY, MATGROUP and EXT_PRODUCT_ID, plus LONGTEXT, MANUFACTMAT, LEADTIME, VENDOR and the custom fields when they have a value. It follows returntarget and, when SAP asks for it, builds the page in ISO-8859-1. Each accepted call and each cart transfer appears on the app's Activity page, with the password masked. It does not support Secure OCI or the background functions DETAIL, VALIDATE and BACKGROUND_SEARCH.

What you do: create the connection in the Shopify admin with SAP (OCI) selected and the company, location and contact it orders as. Send the buyer the OCI URL, username and password. Enter material numbers, units, UNSPSC codes or custom field values per connection where the buyer's mapping needs them, and agree how purchase orders will reach you. If they come as cXML, they land in your PunchRelay inbox, and a Shopify order exists only after you approve one there.

What the buyer does: enter your catalog in their SAP system with the call set to POST, map the fields on their side and test the transfer with their SAP team. The setup guide walks through the connection, OCI and SAP covers the commercial side, and pricing lists the plans.