1 Use item category and pricing date rule in SOAP API – Service Contract – Create, Update (Asynchronous)

1.1 Background

Previously, when creating or updating service contract via SOAP API, there was no item category (ServiceContractItemCategory) and the pricing date rule (BillingPlanPriceDateRule) in the payload. As of SAP S/4HANA Cloud 2002, these two fields are added to the SOAP API.

1.2 Aim

Guide user to understand how the SOAP API works with these two new fields.

1.3 Payload

These two new fields are introduced to the item.

1.4 Why we need the item category in SOAP API

With this field, you can add items for price adaptation via SOAP API and the system populates the price information to billing request lines of the item. However, there are no fields for billing request lines in the SOAP API. You go to the Manage Service Contracts app if you want to change price information to a specific billing request line.

Possible values for item category:

• SCN1: Service contract item.
• SCN2: Service contract item for price adaptation

1.4.1 Create Operation

Case 1: Item category is null or missing in the payload. This case didn’t specify item category so that the system automatically determines the default value SCN1.

Case 2: Specifies SCN1 as item category, and the system creates an item with SCN1.

Case 3: Specifies SCN2 as item category, and the system creates an item with SCN2.

Case 4: Specifies SCN2 as item category and fills price information in price component in the payload. The system creates an item of SCN1 firstly to populate the specified price information to the item and all its billing request lines (BRLs). After that it updates item category to SCN2.

1.4.2 Update Operation

Note that you can only update item category for items whose item category is SCN1. If the item’s item category is SCN2, you can’t update the item category field.

Case 1: Item category is null or missing in the payload. Then nothing updates to item category of the existing item.

Case 2: Updates item category from SCN1 to SCN2

1) No price information updates in price component. The system only changes the item category to SCN2.

2) Fills price information in price component in the payload. The system updates the specified price to the item and all its BRLs firstly. Then it updates item category to SCN2.

Remark: The item category can only be updated when the item status of service contract is open or in progress.

1.5 Why we need the pricing date rule in SOAP API

You can give or change a pricing date to an item for price adaptation via SOAP API.

Possible values for pricing date rule:

• Space: Item Pricing Date
• A: Billing Date in Billing Request Line
• B: Settlement Start Date in Billing Request Line
• C: Settlement End Date in Billing Request Line

1.5.1 Create Operation

Case 1: Specifies SCN1 as item category and pricing date rule is a space, null (<BillingPlanPriceDateRule></BillingPlanPriceDateRule>), or missing in the payload. It will create an item with SCN1, and pricing date rule will be Item Pricing Date by default.

Case 2: Specifies SCN1 as item category and pricing date rule is A, B, or C in the payload. error message will be sent out.

Case 3: Specifies SCN2 as item category and pricing date rule is a space in the payload. It will create an item with SCN2, and pricing date rule will be Item Pricing Date.

Case 4: Specifies SCN2 as item category and pricing date rule is null or missing in the payload. It will create an item with SCN2, and pricing date rule will be Billing Date in Billing Request Line by default.

Case 5: Specifies SCN2 as item category and pricing date rule is A, B, or C in the payload. It will create an item with SCN2, and pricing date rule will be the corresponding value in the possible value list.

1.5.2 Update Operation

Note that you can only update pricing date rule for items whose item category is SCN2. If the item’s item category is SCN1, you can’t update the pricing date rule field.

Case 1: The original item category is SCN2, pricing date rule is null or missing in the payload. There is no change.

Case 2: The original item category is SCN2, specifies pricing date rule as space, A, B, or C in the payload. It updates pricing date rule to the corresponding value in the possible value list.

Case 3: Updates item category from SCN1 to SCN2 and pricing date rule is space, null, or missing in the payload. It only updates item category to SCN2. The pricing date rule remains Item Pricing Date.

Case 4: Updates item category from SCN1 to SCN2 and pricing date rule is A, B, or C in the payload. It updates item category to SCN2, and pricing date rule is updated to the corresponding value in the possible value list.

2 Use header currency in SOAP API Service Contract – Create, Update (Asynchronous)

2.1 Background

Previously, when creating or updating service contract via SOAP API, there was no currency (TransactionCurrency) in the payload. As of SAP S/4HANA Cloud 2002, this field is added to the SOAP API.

2.2 Aim

Guide user to understand how the API works with this new field.

2.3 Payload

This new field is introduced to header.

2.4 Why we need header currency in SOAP API

This makes it possible to set or change a currency different from the default currency defined by company code for individual service contract.

The currency is in ISO currency code, such as USD for United States Dollars.

2.4.1 Create Operation

Case 1: The currency is null, space, or missing in the payload. The system determines a currency that is defined by company code.

Case 2: Specifies a currency different from the default currency defined by company code in the payload. The system takes your input.

2.4.2 Update Operation

Case 1: Updates a different currency for the service contract which hasn’t invoice generated. The system updates the currency accordingly.

Case 2: Updates a different currency for the service contract which have invoice generated. An error message is sent out.

3 Use header payment terms in SOAP API Service Contract – Create, Update (Asynchronous)

3.1 Background

Previously, when creating or updating service contract via SOAP API, there was no payment terms (CustomerPaymentTerms) in the payload. As of SAP S/4HANA Cloud 2002, this field is added to the SOAP API.

3.2 Aim

Guide user to understand how the API works with this new field.

3.3 Payload

This new field is added to the header.

3.4 Why we need header payment terms in SOAP API

This makes it possible to set or change payment terms different from the default one defined by business partner for individual service contract.

You use the key for defining payment terms, composed of cash discount percentages and payment periods.

3.4.1 Create Operation

Case 1: The payment terms is null, space, or missing in the payload. The system determines payment terms defined by business partner.

Case 2: Specifies payment terms different from the default payment terms defined by business partner in the payload. The system takes your input.

3.4.2 Update Operation

Case 1: Updates different payment terms for the service contract. The system updates the payment terms accordingly.

4 Appendix