BAPI_ALM_ORDER_MAINTAIN — BAPI for Creating and Changing PM Orders
BAPI_ALM_ORDER_MAINTAIN creates and changes maintenance and service orders, mirroring transactions IW31 and IW32. It uses a method-driven interface where a table of method entries tells the BAPI which object (header, operation, component, partner) to create or update, and it does not commit on its own — the caller must issue BAPI_TRANSACTION_COMMIT explicitly after checking the RETURN table for errors.
This page covers the interface pattern of BAPI_ALM_ORDER_MAINTAIN, the method-table driven approach it uses instead of a flat parameter list, and the specific ways integrations get the RETURN table and the commit sequence wrong. It also covers where responsibility for a failed order creation typically sits between functional and technical teams.
Published 16 Sept 2026· 1,002 words
What it does
BAPI_ALM_ORDER_MAINTAIN acts on the plant maintenance order and the customer service order, the same object behind transactions IW31 (create) and IW32 (change). Unlike simpler BAPIs with one flat structure per business object, this one is built around a method table: each row names an object type (header, operation, component, partner, object list entry, and so on) and an action (create, change, delete), and the corresponding data tables carry the payload for that row. A single call can create the order header, add several operations, attach components, and assign partners in one shot, which is why it is the standard interface for mass order creation and for middleware that generates PM orders from external maintenance systems.
Important parameters
- IT_METHODS - the driver table; each entry carries REFNUMBER (a caller-assigned temporary key), OBJECTTYPE (HEADER, OPERATION, COMPONENT, PARTNER, etc.), METHOD (CREATE, CHANGE, DELETE) and OBJECTKEY, telling the BAPI which data row to apply and how
- IT_HEADER - order header fields: order type, planning plant, functional location, equipment, priority, basic dates, one row per REFNUMBER used for a header create or change
- IT_HEADER_UP - update indicator flags matching IT_HEADER; a field populated in IT_HEADER without its flag set in IT_HEADER_UP is silently ignored on change
- IT_OPERATION and IT_OPERATION_UP - operation-level data (work center, control key, durations) and the matching update flags
- IT_COMPONENT and IT_COMPONENT_UP - material or non-stock component assignments for the order
- IT_PARTNER - partner assignments (person responsible, ordering party) linked by partner function
- RETURN - the standard BAPIRET2 message table returned by every call
- ET_NUMBERS - maps each REFNUMBER used for a header create to the real order number generated once the save completes
Commit behaviour
The BAPI does not commit. It builds the order in the update task of the current LUW and expects an explicit call to BAPI_TRANSACTION_COMMIT afterward. If the caller skips the commit, the call returns success messages and ET_NUMBERS still shows a generated order number, but nothing is written to the database once the session ends, and the next attempt to read that order number fails or returns nothing. This produces a specific and confusing symptom: the interface log shows success, the order genuinely does not exist, and the root cause is a missing commit rather than a BAPI failure. Some callers add a WAIT parameter or a short delay after the commit when the same LUW immediately re-reads the order; without it, a subsequent BAPI_ALM_ORDER_GET_DETAIL call can occasionally run against buffers that have not caught up yet.
Return handling
RETURN is a table, not a single message, and it must be scanned in full before deciding whether to commit. A success message on order creation typically appears alongside warnings about defaulted fields or missing customizing that did not stop the save but should not be ignored. The recurring interface bug is checking only sy-subrc after the BAPI call — which stays zero regardless of content in RETURN — or checking only the first line and committing anyway. That commits a partially built order: header created, but a component line rejected for a missing material-plant extension, with no rollback because the commit already happened. The correct pattern is to loop RETURN checking TYPE against E and A, abort the commit if either is present, and only then call BAPI_TRANSACTION_COMMIT. Equally important is reading ET_NUMBERS rather than assuming the order number appears inside a RETURN message text; REFNUMBER is a caller-chosen temporary key and the real order number only exists after the method table has been processed.
ECC vs S/4HANA
BAPI_ALM_ORDER_MAINTAIN remains the standard programmatic interface for order creation and change on S/4HANA; there is no released replacement API that supersedes it for this object. Fiori maintenance apps use their own OData services internally, but custom integrations, migration tooling, and interface development for PM and CS orders still build on this BAPI in the same way they did on ECC. The method-table pattern and the commit requirement are unchanged.
Common pitfalls
- Field populated in a data table (IT_HEADER, IT_OPERATION) but the matching flag left blank in the _UP structure, so the change is accepted with no error and simply not applied
- REFNUMBER reused or left blank across multiple method rows in a mass-creation loop, causing rows meant for different orders to be merged into one
- Order type and planning plant combination not configured for order creation, surfacing as a customizing error deep in RETURN rather than a clear failure at the top
- Component line referencing a material not extended to the order's plant, rejecting only that method row while the header commits regardless
- Missing BAPI_TRANSACTION_COMMIT after a batch of calls in a background job, leaving orders that appear in the job log as created but are absent from the database
- Control key on an operation not permitting the requested action (confirmation, costing), rejected silently unless RETURN is read line by line
Whose problem this is
A rejected method row (missing customizing, wrong order type, unextended material) is functional configuration work; a missing commit, a dropped update flag, or a mishandled RETURN loop is a developer defect in the calling program. Evidence to bring to either side is the full RETURN table content and the IT_METHODS payload actually sent, not just a summary that says the call failed.
Related SAP objects
Reviewed pages this object connects to in the ERPClimb knowledge graph.
Source: ERPClimb — https://erpclimb.com/sap-bapis/bapi-alm-order-maintainERPClimb is an independent platform and is not affiliated with SAP SE. Reference pages are written and reviewed by SAP consultants for learning and troubleshooting.