SAP Knowledge Base Article - Public

3702879 - Error "You must not change billingplanitemusage" encountered when using patch method in commercial project API

Symptom

In the "Try Out" page of the API Commercial Project - Create, Update, for a customer project, when trying to change the existing billing plan item usage (e.g., from "Time and Expenses" to "Payment on Account"), receive the error message in the response: "You must not change BILLINGPLANITEMUSAGE". However, it is possible to manually change the billing plan item usage in the "Plan Customer Project" app.

Environment

SAP S/4HANA Cloud Public Edition

Reproducing the Issue

  1. Open the API hub tryout section.
  2. Choose entity A_CustProjSlsOrdItmBillgPlnItm for a PATCH call.
  3. Provide the parameters and the request body.
  4. Click on "Run".

Resolution

Below are the detailed explanations regarding why "changing BillingPlanItemUsage via API" is not supported:

(1) Product Development Perspective:

The development teams have confirmed that the decision to restrict PATCH operations for the BillingPlanItemUsage property is intentional. This is because, the BillingPlanItemUsage field is interconnected with all other fields in the A_CustProjSlsOrdItmBillgPlnItm entity. Technically, allowing users to modify this field via API could inadvertently invalidate other field values, and as a result, the users would need to re-enter all dependent values again within the same changeset. Providing this option in the API would bring a very high risk of accidentally deleting values. To mitigate this risk, the API is designed to return the error message "You must not change BILLINGPLANITEMUSAGE" to let users know that they cannot change this field.

The reason why it is possible to manually change the billing plan item usage in the "Plan Customer Projects" app, lies in that the interface guides users to re-enter values without affecting other fields.

(2) User Assistance Perspective:

Regarding why BillingPlanItemUsage is included in the "Try Out" documentation for the "PATCH" method, the reason lies in that, the "Try out" functionality on the API Hub always by default includes all properties. The "Try Out" examples are generated automatically and do not consider the detailed dependencies, because the details regarding which exact property is supported by the corresponding operation, are already indicated in the Help documentation for the API and even directly embedded within the product response, like the error message in the "Symptom" section.

For example, at the top of the "Properties" section in the Help Documentation Sales Order Item Billing Plan, it is pointed out that: "The table below lists the information for the Create (POST) operation". Within the same documentation, under the "Update (PATCH/MERGE)" operation, it is also pointed out that: "Whether you can change a specific property or not depends on the general system behavior, your system settings, and the current document status". This means that not all fields that are listed in the documentation for the Create (POST) operation support all other operations. The UA team cannot document all operations for all properties, as there are too many different scenarios with dependencies where fields will behave in different ways. The detailed scenario for the behaviour of each property are usually documented in the response during the product usage, such as the error message in the "Symptom" section.

See Also

Keywords

billingplanitemusage, patch method, commercial project api, plan customer projects app, error message, time and expenses, payment on account, api restriction, sales order item billing plan, field dependencies. , KBA , SD-SLS-PBS , Project-Based Services in Sales Documents , Problem

Product

SAP S/4HANA Cloud Public Edition all versions