Skip to content
Gatebold

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, strict syntax, no mixed-content from an HTTPS catalogue.
  • ~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.