Skip to Content
Product Information
Author's profile photo Martin McCormick

API How To: ETag Handling for Change Operations


As you work with APIs from SAP S/4HANA Cloud (S/4HC), you may encounter some APIs that have a built in feature for change control that require additional handling when calling the API known as an ETag. The sales order API is a common API that requires the use of ETags when modifying an order.

In this blog, we’ll take a quick look at an example of how to handle ETags when they are required to call SAP S/4HC APIs. Entity Tags, or ETags is basically version control for updating documents over OData. It’s to make sure you are working and updating the latest version of a document. This is done as a parameter in the HTTP Header that provides version information on the document requested/updated. This is required for OData services because a resource is not locked for updating ahead of the update (i.e. before being called) and is called an opportunistic locking. There are many resources available on the internet with good info on ETags, but here is a good overview blog. ETags are not required for document creation.

As an example of how ETags function, let’s imagine that you have a billing document with a line item that has 5 items to be picked. While you are making your call to pick 4 items, another system has come along and picked all 5 items thereby leaving none left to pick. Your call would now fail when you go to pick 5 items because there arent 5 left to be picked as you are working with data from an older version of the document. To prevent this situation you fetch the document version ahead of the update and present this version as part of your update for S/4HC to validate that you have the latest version. For example, document with 5 items to be picked is v002. The non SAP S/4HC system fetches the document version first and puts v002 into the ETag header. Now the other resource comes along and picks 4 the document version increases to v003. Now my OData call with fail because I am not working with the correct version of the document (v002 vs v003). This logic is used in many of the SAP APIs to provide data consistency and integrity.


In this example, we will use the Outbound Delivery API from SAP S/4HC:

This API is unique because not only does it have OData services, it also has a series of HTTPS services that accept only an HTTP POST using query string parameters around the topic of picking.

For this blog, we’ll test using Postman but you can implement this same logic in an iFlow on SAP Cloud Platform Integration (CPI).

The first step is to call the API to fetch the x-csrf-token AND the ETag values. We’ll work with delivery document 800000037 and line item 20. You will find the values returned in the Header response, highlighted in yellow in the below image.


To update the batch, we need to set the header values in our request and then form the JSON payload for updating the delivery document. This is shown in the next two screen shots.

The batch is updated in SAP:

In the next step, a call the picking service to update picked quantity is made. This is one of the services available in the API hub described above. What’s unique about these services is that they only take a URL with query string parameters (no body) and the only response is an HTTP 200 for a success or an error message.

If this service was being called on its own, we would need to fetch the x-csrf-token and the ETag value but since we just updated the document for batch number we can simply increment our ETag value by 1 and reuse the same x-csrf-token.


The reply indicates a successful call:

Picking quantity is updated in SAP S/4HC:

You could keep calling different services, for example, you might want to call the Post Goods Issue (PGI) service to do a PGI on the document. You just need to increment ETag by 1 and call the PGI service, /PostGoodsIssue (assuming nothing else has come along and called your document in the meantime or an end user saved the document in SAP S/4HC).

In addition, you can test all of these services in the API hub too–you don’t have to use Postman.

I hope you found this blog useful.


Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Amith Nair
      Amith Nair

      Thank you Marty! Was in a look out for the applicability of ETag w.r.t OData services, Thanks for sharing this blog!

      Author's profile photo Enda Fennelly
      Enda Fennelly

      nice blog Marty - thank you for creating

      Author's profile photo Mohini Verma
      Mohini Verma

      Hi Marty,

      Nice blog! I am trying something similar but facing some issues. Here are the details -

      we try to confirm a WT in S/4HANA Cloud with the API

      We can GET the warehouse task but the POST of the confirmation would not work. Error we get is

          "error": {
              "code": "SADL_ENTITY_RUNTIME/005",
              "message": "State of entity CDS~A_WAREHOUSETASK_2 with key 1750 001000000801 0000 was already changed (stale If-Match)",
              "target": "$Parameter/_it",
              "@SAP__common.ExceptionCategory": "Provider_Application_Error",
              "innererror": {
                  "ErrorDetails": {
                      "@SAP__common.Application": {
                          "ComponentId": "BC-ESI-ESF-GW",
                          "ServiceRepository": "SRVD_A2X",
                          "ServiceId": "API_WAREHOUSE_ORDER_TASK_2",
                          "ServiceVersion": "0001"
                      "@SAP__common.TransactionId": "D2EACF0F9EE40290E00628D659E8AB38",
                      "@SAP__common.Timestamp": "20220525084803.779731",
                      "@SAP__common.ErrorResolution": {
                          "Analysis": "Use ADT feed reader \"SAP Gateway Error Log\" or run transaction /IWFND/ERROR_LOG on SAP Gateway hub system and search for entries with the timestamp above for more details",
                          "Note": "See SAP Note 1797736 for error analysis ("

      We are sending a If-Match in the header which looks like this W/"'SADL-020220510061831C\~20220510061831'/" not sure if it is correct. This e-tag is fetched with a previous GET of the warehouse task. It's hard to find any documentation on what is expected. How can we submit a post successfully?


      Author's profile photo Martin McCormick
      Martin McCormick
      Blog Post Author

      Hi Mohini

      Can you confirm that you are using v4 of the Warehouse API?  v2 is deprecated and I think going away in June:

      To your question, your etag looks correct--can you provide the sequence of steps leading up to the POST?  You aren't reusing the etag right?