What is an OCI field?

An OCI field is a form-urlencoded HTTP parameter used in the SAP Open Catalog Interface protocol. Cart return fields are prefixed NEW_ITEM- and indexed per line (NEW_ITEM-DESCRIPTION[1], NEW_ITEM-DESCRIPTION[2], etc.). Setup request parameters are global and not indexed (USERNAME, PASSWORD, HOOK_URL, ~OkCode, ~Target, etc.).

Which OCI cart-return fields are required?

Five fields are required on every cart line: NEW_ITEM-DESCRIPTION (label, max 40 chars), NEW_ITEM-QUANTITY (positive decimal), NEW_ITEM-UNIT (unit code), NEW_ITEM-PRICE (decimal with dot separator) and NEW_ITEM-CURRENCY (3-letter ISO 4217 code).

Which OCI setup-request parameters are required?

Three minimum parameters: USERNAME (session credential), PASSWORD (password or session token, send via POST) and HOOK_URL (absolute cart-return URL, HTTPS recommended). The ~OkCode, ~Target, ~Caller and LANGU parameters are optional but almost always present in practice.

Which fields are specific to OCI 5.0?

OCI 5.0 added fields for attachments (NEW_ITEM-ATTACHMENT, ATTACHMENT_TITLE, ATTACHMENT_PURPOSE), external product references (NEW_ITEM-EXT_PRODUCT_ID, EXT_SCHEMA_TYPE) and external categories (EXT_CATEGORY_ID, EXT_CATEGORY). On the setup side, RETURNTARGET was introduced in 5.0. Adoption remains limited to large industrial groups on recent S/4HANA.

What is the difference between PRICE and PRICEUNIT?

PRICE is the unit price for PRICEUNIT units. If PRICEUNIT is not sent, SAP uses the default value 1 (price per unit). If PRICEUNIT=1000 and PRICE=12.50, this means 12.50 EUR for 1000 units. This is the #1 source of x100 / x1000 pricing errors in OCI integration when the buyer does not map PRICEUNIT.

What is sapevent:post in the OCI cart return (HOOK_URL)?

In legacy SAP GUI scenarios (ITS / WebGUI, etc.), the HOOK_URL passed by SAP can contain a sapevent: pseudo-URL: the cart-return form then posts to sapevent:post and the embedded browser converts the submit into an SAP event that passes the NEW_ITEM-* fields back to the SAP transaction. In web scenarios (SRM, S/4HANA, etc.), HOOK_URL is a standard HTTPS URL and the cart return is a plain form POST to that URL.

OCI Reference

All OCI 4.0 and 5.0 fields at a glance.

38 documented fields: cart return (NEW_ITEM-*) and setup request (USERNAME, HOOK_URL, ~OkCode, etc.). Format, length, version, FR + EN descriptions.

To test a real OCI payload against these rules, use the OCI validator or browse the examples library.

OCI fields reference

Every OCI 4.0 and 5.0 field recognised by the validator, with expected format, max length and description. 38 fields total.

OCI 4.0 + 5.0

Filter

Notation: [i] = field repeated per cart line (i = line number, starting at 1).

NEW_ITEM-DESCRIPTION[i]

Required string(40) Cart return

Short item label as it will appear in the buyer cart. Truncated to 40 chars by SAP.
NEW_ITEM-MATNR[i]

Optional string(40) Cart return

Supplier item number in the buyer system. Used when the buyer keeps a material master.
NEW_ITEM-MATGROUP[i]

Optional string(9) Cart return

Material group or classification. In international B2B, this is often an 8-digit UNSPSC code.
NEW_ITEM-QUANTITY[i]

Required decimal Cart return

Ordered quantity. Positive decimal, dot as decimal separator (never comma).
NEW_ITEM-UNIT[i]

Required unit(3) Cart return

Unit of measure. OCI spec = ISO/UN/ECE code (PCE, KGM, MTR, etc.). Many SAP installations expect internal T006 codes (ST, KG, M, etc.) - the validator flags both cases.
NEW_ITEM-PRICE[i]

Required decimal Cart return

Unit price (for PRICEUNIT units, default 1). Decimal, dot as separator. Always validate PRICE / PRICEUNIT / QUANTITY coherence.
NEW_ITEM-PRICEUNIT[i]

Optional integer Cart return

Quantity that PRICE refers to. If PRICE=12.50 and PRICEUNIT=1000, the price is 12.50 per 1000 units. Absent = 1. The #1 source of x100 / x1000 pricing bugs in production.
NEW_ITEM-CURRENCY[i]

Required currency(3) Cart return

ISO 4217 currency code (EUR, USD, GBP, etc.). 3 uppercase letters.
NEW_ITEM-DELIVERYDATE[i]

Optional date(10) Cart return

Requested delivery date in ISO 8601 format (YYYY-MM-DD). Heavily used in MRO and indirect procurement.
NEW_ITEM-VENDOR[i]

Optional string(10) Cart return

Vendor number in the buyer system. Must match the pre-registered vendor on the SAP side, otherwise the item is rejected.
NEW_ITEM-VENDORMAT[i]

Optional string(40) Cart return

Vendor item reference (SKU, catalogue product code).
NEW_ITEM-MANUFACTCODE[i]

Optional string(10) Cart return

Manufacturer code (distinct from vendor when the item is resold).
NEW_ITEM-MANUFACTMAT[i]

Optional string(40) Cart return

Manufacturer part number (MPN).
NEW_ITEM-CONTRACT[i]

Optional string(10) Cart return

Buyer-side framework contract number, when the item is linked to a negotiated contract.
NEW_ITEM-CONTRACT_ITEM[i]

Optional integer(5) Cart return

Contract line item. Required when CONTRACT is filled.
NEW_ITEM-SERVICE[i]

Optional flag(1) Cart return

Service flag. 'X' = service line item (no physical goods), empty = physical good.

Allowed values : X
NEW_ITEM-LEADTIME[i]

Optional integer(5) Cart return

Lead time in calendar days.
NEW_ITEM-LONGTEXT_1:132[i]

Optional string Cart return

Long descriptive text, when DESCRIPTION (40 chars) is too short. Special syntax: NEW_ITEM-LONGTEXT_i:132[] where i is the line index and 132 is the max width of a text "line".
NEW_ITEM-CUST_FIELD1[i]

Optional string(10) Cart return

Custom field 1, free-form. Convention is buyer-specific.
NEW_ITEM-CUST_FIELD2[i]

Optional string(10) Cart return

Custom field 2, free-form.
NEW_ITEM-CUST_FIELD3[i]

Optional string(10) Cart return

Custom field 3, free-form.
NEW_ITEM-CUST_FIELD4[i]

Optional string(10) Cart return

Custom field 4, free-form.
NEW_ITEM-CUST_FIELD5[i]

Optional string(10) Cart return

Custom field 5, free-form.
NEW_ITEM-ATTACHMENT[i]

Optional url(255) Cart return OCI 5.0

URL of an attachment (datasheet, drawing, photo). HTTPS recommended, publicly accessible or via the buyer authentication tunnel.
NEW_ITEM-ATTACHMENT_TITLE[i]

Optional string(50) Cart return OCI 5.0

Displayable title of the attachment (otherwise the file name extracted from ATTACHMENT is used).
NEW_ITEM-ATTACHMENT_PURPOSE[i]

Optional enum(20) Cart return OCI 5.0

Attachment category. Typical values: DATASHEET, DRAWING, PHOTO, CERTIFICATE, OTHER, etc.

Allowed values : DATASHEET, DRAWING, PHOTO, CERTIFICATE, OTHER
NEW_ITEM-EXT_PRODUCT_ID[i]

Optional string(40) Cart return OCI 5.0

External product identifier (GTIN, EAN, etc.). Used with EXT_SCHEMA_TYPE to indicate the referential.
NEW_ITEM-EXT_SCHEMA_TYPE[i]

Optional enum(20) Cart return OCI 5.0

Schema of EXT_PRODUCT_ID. Values: GTIN, EAN, UPC, UNSPSC, ECLASS, OTHER.

Allowed values : GTIN, EAN, UPC, UNSPSC, ECLASS, OTHER
NEW_ITEM-EXT_CATEGORY_ID[i]

Optional string(40) Cart return OCI 5.0

External category identifier (UNSPSC, eCl@ss, etc.). Complements MATGROUP.
NEW_ITEM-EXT_CATEGORY[i]

Optional string(60) Cart return OCI 5.0

External category label associated with EXT_CATEGORY_ID.
USERNAME

Required string(40) Setup

Session credential authenticating the buyer to the supplier catalogue. Not a user login.
PASSWORD

Required string(40) Setup

Session password or token. Send via POST (not GET) to avoid leaking the secret into server logs.
HOOK_URL

Required url(255) Setup

Absolute URL to which the supplier catalogue will POST the cart return. HTTPS very strongly recommended.
~OkCode

Optional enum(4) Setup

SAP action triggered on return. ADDI = add to current cart (standard), CRTE = direct purchase requisition creation. Use ADDI unless your SRM requires otherwise.

Allowed values : ADDI, CRTE
~Target

Optional enum(10) Setup

Target frame for the return form. _top = escapes all frames (recommended), _parent = bubbles up one frame, _self = stays in the current frame (often causes "cart never returns" bugs).

Allowed values : _top, _parent, _self
~Caller

Optional enum(4) Setup

Calling SAP module. CTLG = catalogue (default), SC = Shopping Cart, PO = Purchase Order. Only affects display on the ERP side.

Allowed values : CTLG, SC, PO
LANGU

Optional string(2) Setup

Language code, 1 or 2 letters (E, D, F, EN, DE, FR, etc.). Lets the catalogue render in the right language.
RETURNTARGET

Optional string(20) Setup OCI 5.0

Tells the supplier the return target window when HOOK_URL is served in a new window. Rarely used.

How to read this reference

OCI (SAP Open Catalog Interface) is not XML: it is a protocol based on HTTP form-urlencoded parameters. Every cart-return payload contains NEW_ITEM-FIELD[i]=value pairs, where i is the line index (starting at 1). Setup request parameters are global and prefixed differently (sometimes with ~ for SAP-reserved parameters).

For each field, the table shows:

Exact name (case-sensitive on the SAP side), followed by [i] if the field is repeated per line.
Status required or optional per the OCI 4.0 spec.
Type and max length: SAP silently truncates oversized values.
Mode: cart return or setup request.
OCI version: most fields exist since 4.0, some were added in 5.0 (attachments, external product references, etc.).
Description bilingual with usage context and known traps.

The fields you must know

NEW_ITEM-PRICEUNIT - the #1 source of x1000 pricing bugs in production. Always map it on the buyer side.
NEW_ITEM-MATGROUP - material group, often an 8-digit UNSPSC code. See the UNSPSC reference.
NEW_ITEM-UNIT - UN/ECE codes per the spec (PCE, KGM, MTR), but most SAP installations expect internal T006 codes (ST, KG, M). Coordinate the unit mapping with the buyer.
HOOK_URL - absolute URL where the supplier POSTs the cart. Always HTTPS in web scenarios, strict syntax, no mixed-content from an HTTPS catalogue. In legacy SAP GUI scenarios (ITS / WebGUI, etc.), HOOK_URL can instead contain a sapevent: pseudo-URL: the cart-return form then posts to sapevent:post and the embedded browser turns the submit into an SAP event that hands the NEW_ITEM-* fields back to the transaction.
~Target - target of the cart-return auto-submit form. Three possible values:
- _top (recommended): breaks out of all frames and POSTs to the top-level browser window, so the SRM intercepts the cart normally.
- _self: POSTs within the current frame. If the catalogue runs in an iframe (standard SAP SRM setup), the return stays trapped inside the iframe and the SRM never sees anything → HOOK_URL never fires and the cart vanishes.
- _parent: goes up only one frame. Risky if there are nested iframes (reverse proxy + SRM Portal).

OCI 4.0 or OCI 5.0?

OCI 4.0 remains the de-facto standard across the vast majority of the installed base. OCI 5.0 added attachments, external product references (GTIN, EAN, UNSPSC, eCl@ss, etc.) and a richer service hierarchy. Start with 4.0, add 5.0 fields only when the buyer explicitly requests them. See the full OCI article.

Going further

OCI Validator - test an OCI payload (setup request or cart return) against all the rules documented here, 100% in your browser.
OCI payload examples - 7 curated examples (minimal, complete, PRICEUNIT trap, OCI 5.0 attachments, etc.) ready to copy or test directly in the validator.
cXML Validator - the equivalent for the cXML protocol, validation against the official 1.2.070 DTD.
cXML vs OCI - full protocol comparison.
UNSPSC Codes - the product/service referential for the NEW_ITEM-MATGROUP field.