OCI (Open Catalog Interface): the SAP Standard for External Catalogs
How the jump to the supplier shop and the return of the shopping cart work technically
OCI is the interface defined by SAP through which a procurement system calls an external web catalog and receives the cart filled there as line item data. This entry explains the flow, the return fields with a concrete example, and how OCI differs from cXML.
- Call and return flow step by step
- Return fields with an example
- OCI versions at a glance
- OCI compared with cXML
What Is OCI?
OCI (Open Catalog Interface) is a standard defined by SAP that lets a procurement system call an external web catalog and receive the selected items back as structured line item data. The user jumps from a shopping cart or purchase requisition to the supplier shop, selects items and transfers them to the calling system through a form post.
What OCI Covers and What It Does Not
OCI defines exactly two things: how the procurement system calls the catalog, and in what form the catalog returns the selected items. The standard originated in SAP's procurement products (Enterprise Buyer, later SAP SRM) and is now supported by SAP ERP, S/4HANA and many procurement systems from other vendors.
OCI does not transmit purchase orders, order confirmations or invoices. The purchase order is created in the procurement system once the returned items have been checked and approved there, and it reaches the supplier through a separate channel such as email, EDI or cXML. If you want to exchange order and invoice documents over the same protocol, cXML is the usual choice.
Call and Return: the OCI Flow Step by Step
The whole flow runs through the user's browser. No direct server connection between procurement system and catalog is required, which keeps integration simple even across company boundaries.
Select a catalog
The user creates a shopping cart or purchase requisition in the procurement system and picks one of the external catalogs configured there.
Call with parameters
The procurement system calls the catalog URL and passes the parameters maintained in its configuration: login data for the shop, further values agreed with the supplier, and the return address in the HOOK_URL parameter. Fixed additional parameters such as ~OkCode=ADDI, ~target=_top and ~caller=CTLG control processing on the SAP side.
Shop in the catalog
The catalog logs the user in based on the data received and shows the assortment with customer-specific prices. The user searches, configures and adds items to the shop's cart.
Return to the HOOK_URL
Instead of checking out in the shop, the user clicks the transfer button. The shop generates an HTML form with one set of NEW_ITEM fields per item and posts it through the browser to the HOOK_URL.
Transfer into the procurement system
The procurement system reads the fields, creates items in the shopping cart or purchase requisition and adds account assignment, plant and delivery address. Approval and ordering then follow the customer's own rules.
https://shop.supplier.example/oci
?USERNAME=customer_4711
&PASSWORD=********
&HOOK_URL=https%3A%2F%2Fprocurement.customer.example%2Foci%2Freturn
&~OkCode=ADDI
&~target=_top
&~caller=CTLGOCI Example: Typical Return Fields
The return consists of name-value pairs. Each item gets a sequential index in square brackets, starting at 1. The example below shows a cart with two items as a shop would post it to the HOOK_URL.
| Field | Content | Note |
|---|---|---|
| NEW_ITEM-DESCRIPTION[n] | Short text of the item | 40 characters at most; longer texts belong in the long text |
| NEW_ITEM-MATNR[n] | Material number in the customer's SAP system | Only useful if the shop knows the customer's material numbers |
| NEW_ITEM-QUANTITY[n] | Quantity | Decimal point as separator |
| NEW_ITEM-UNIT[n] | Unit of measure | ISO code, for example PCE for piece |
| NEW_ITEM-PRICE[n] | Price per price unit | Decimal point, no thousands separators |
| NEW_ITEM-PRICEUNIT[n] | Price unit | Quantity the price refers to, such as 1 or 100 |
| NEW_ITEM-CURRENCY[n] | Currency | ISO code, for example EUR |
| NEW_ITEM-LEADTIME[n] | Lead time | In days |
| NEW_ITEM-VENDOR[n] | Vendor number in the customer's system | Important for catalogs covering several suppliers |
| NEW_ITEM-VENDORMAT[n] | Supplier's part number | Carried over into the purchase order |
| NEW_ITEM-MANUFACTCODE[n] | Manufacturer number | Used together with NEW_ITEM-MANUFACTMAT[n], the manufacturer part number |
| NEW_ITEM-MATGROUP[n] | Material group | Must exist in the procurement system or be mapped there |
| NEW_ITEM-CONTRACT[n] | Contract number | With NEW_ITEM-CONTRACT_ITEM[n] for the contract item |
| NEW_ITEM-SERVICE[n] | Service indicator | Distinguishes services from material items |
| NEW_ITEM-EXT_PRODUCT_ID[n] | Unique product identifier in the catalog | Basis for later detail and validation calls |
| NEW_ITEM-LONGTEXT_n:132[] | Long text of item n | Here the index comes before the colon |
| NEW_ITEM-EXT_SCHEMA_TYPE[n] | Classification scheme | Used with NEW_ITEM-EXT_CATEGORY_ID[n] to map to material groups |
| NEW_ITEM-CUST_FIELD1[n] to CUST_FIELD5[n] | Freely usable fields | Their meaning is agreed between customer and supplier |
<form method="post" action="[HOOK_URL]">
<input type="hidden" name="NEW_ITEM-DESCRIPTION[1]" value="Hex bolt M8x40 zinc-plated">
<input type="hidden" name="NEW_ITEM-QUANTITY[1]" value="200">
<input type="hidden" name="NEW_ITEM-UNIT[1]" value="PCE">
<input type="hidden" name="NEW_ITEM-PRICE[1]" value="4.90">
<input type="hidden" name="NEW_ITEM-PRICEUNIT[1]" value="100">
<input type="hidden" name="NEW_ITEM-CURRENCY[1]" value="EUR">
<input type="hidden" name="NEW_ITEM-LEADTIME[1]" value="3">
<input type="hidden" name="NEW_ITEM-VENDORMAT[1]" value="SK-M8X40-ZN">
<input type="hidden" name="NEW_ITEM-MATGROUP[1]" value="FASTENERS">
<input type="hidden" name="NEW_ITEM-DESCRIPTION[2]" value="Safety glasses clear, EN 166">
<input type="hidden" name="NEW_ITEM-QUANTITY[2]" value="10">
<input type="hidden" name="NEW_ITEM-UNIT[2]" value="PCE">
<input type="hidden" name="NEW_ITEM-PRICE[2]" value="3.45">
<input type="hidden" name="NEW_ITEM-PRICEUNIT[2]" value="1">
<input type="hidden" name="NEW_ITEM-CURRENCY[2]" value="EUR">
<input type="hidden" name="NEW_ITEM-LEADTIME[2]" value="2">
<input type="hidden" name="NEW_ITEM-VENDORMAT[2]" value="PPE-4711">
<input type="hidden" name="NEW_ITEM-MATGROUP[2]" value="PPE">
</form>In practice every item needs at least a short text or a material number plus quantity and unit of measure. For items without a customer material number, procurement systems also expect price and currency. Besides the form variant, the specification defines an XML variant of the return; the HTML form is what you will usually encounter.
Additional Functions: Detail, Validation and Search
Beyond the normal catalog call, OCI describes optional functions that are triggered through the FUNCTION parameter. FUNCTION=DETAIL lets the procurement system open the detail view of an item it has already received; FUNCTION=VALIDATE has price and availability of an item checked again, for example when a saved cart is reused later. Both identify the item by the product identifier the shop supplied earlier in NEW_ITEM-EXT_PRODUCT_ID. FUNCTION=SOURCING opens the catalog directly with a search term.
Not every shop supports these functions. Before connecting a catalog, clarify which of them your procurement system uses and which the supplier offers.
OCI Versions
SAP has published the specification in several versions, including 2.0, 3.0, 4.0 and 5.0. The core return fields shown above have remained stable across versions; later versions mainly added fields and optional functions. Supplier shops usually state which version they support, most often 4.0 or 5.0.
For an integration project the version number matters less than the question of which fields the procurement system actually evaluates and which the shop can fill. That alignment belongs in every field mapping.
OCI or cXML?
| Criterion | OCI | cXML |
|---|---|---|
| Origin | SAP | Ariba |
| Data format | Name-value pairs in URL and HTML form | XML documents |
| Session setup | Direct call of the catalog URL with parameters | PunchOutSetupRequest and PunchOutSetupResponse between the servers, then browser redirect |
| Cart return | Form with NEW_ITEM fields posted to the HOOK_URL | PunchOutOrderMessage |
| Process covered | Catalog call and cart return | Punchout plus purchase order, confirmation, ship notice and invoice as separate documents |
| Typical environment | SAP ERP, SAP SRM, S/4HANA and SAP-oriented procurement systems | SAP Ariba and other procurement platforms |
Many suppliers offer both protocols. The choice therefore usually follows the customer's procurement system rather than the supplier's preference.
Related Terms and Matching Ovenca Modules
- Setting up the OCI interface
Call structure, field mapping, testing and typical errors in the technical integration.
- OCI catalog
What an OCI catalog is from the buyer's and the supplier's point of view, and when it beats a static catalog.
- Punchout catalog
The principle of jumping to the supplier shop, independent of the protocol.
- cXML
The XML-based counterpart to OCI with additional document exchange.
- Catalog shop with a central punchout cart
Imported catalogs and punchout shops in one search and one cart.
- Catalog procurement with SAP S/4HANA
How Ovenca connects to S/4HANA via OCI, cXML or API.
OCI in Four Points
What procurement and IT should know about the standard
Called from the procurement system
The external catalog is set up in the procurement system as a web service. The call passes login data and the HOOK_URL return address to the shop.
- Catalog URL and parameters in configuration
- HOOK_URL as return address
- Flow runs through the user's browser
Returned as line item data
The shop posts the cart back as a form with NEW_ITEM fields. These become items in the shopping cart or purchase requisition.
- One set of fields per item
- Short text, quantity, unit, price, currency
- Supplier part number and material group
Ordering stays in the procurement system
OCI ends when the items are handed over. Account assignment, approval and ordering follow the customer's rules in its own system.
- Approval by value limits
- Purchase order through a separate channel
- No documents via OCI
Alignment rather than programming
Most of the effort goes into aligning units of measure, material groups and character sets between shop and procurement system.
- Units of measure as ISO codes
- Material group mapping
- Tests with real carts
How Ovenca Uses OCI
Ovenca uses OCI in both directions: to connect external supplier shops to the catalog shop, and to connect the catalog shop to your ERP.
- Connect supplier shops via OCI
- External shops are connected through OCI punchout. You manage the OCI parameters per supplier in the admin area.
- One cart for all sources
- Items from imported catalogs and from punchout shops end up in one central cart and run through the same approval.
- OCI and cXML side by side
- Ovenca supports OCI and cXML as equivalent punchout protocols. You do not have to settle on one.
- Integration with SAP
- Ovenca connects to SAP ERP and S/4HANA via OCI punchout, cXML or API.
- Controlled access
- Roles and permissions determine which users may use which punchout catalogs.
- Operated on your terms
- Ovenca runs on-premise, in a private cloud or hybrid and is in use worldwide at LANXESS; the collaboration dates back to 2014.
OCI: Questions and Answers
Related pages
Use OCI Catalogs in Your System Landscape
We show you how supplier shops are connected to a central catalog shop via OCI and cXML and handed over to your ERP.