How to Prepare a Deep Payload for Business Partner Master Data (API_BUSINESS_PARTNER)

[Maniems]

In this blog, we’ll explore how to prepare deep payloads for the OData V2 API API_BUSINESS_PARTNER in Business Partner for different scenarios.

When integrating with SAP S/4HANA Cloud Public Edition or SAP S/4HANA Cloud Private Edition OData APIs, we often need to create or update multiple related entities together — such as a Business Partner with its Customer, Supplier, Bank, or Identification details. Instead of multiple sequential API calls,  we can use the Deep Insert concept, allowing us to create related entities in a single request.

We’ll understand what POST and Deep POST calls are in OData, how to analyze metadata, and how to structure payloads for different scenarios — such as creating a Business Partner along with a Customer, Supplier, or Bank / Identification details — all in a single request.

Understanding the Supported Operations for API_BUSINESS_PARTNER

API_BUSINESS_PARTNER provides the following key operations:
- POST: Create a new business partner record
- GET (READ): Retrieve existing data
- PATCH: Update existing data
- DELETE: Delete a record

A POST call is used to create a single entity.
A Deep POST (Deep Entity) is used to create a parent entity and related child entities together in a single API call.

What is a Deep POST Call?

What is a Deep Payload in Business Partner Creation?

A deep payload = Creating Business Partner + related dependent entities in a single POST.

Example:
Business Partner (root entity) and one or more of the following dependent entities

• Business Partner Address
• Customer
• Customer Company Code
• Customer Sales Area
• Supplier
• Supplier Company
• Supplier Purchasing Org
• Communication (Email, Phone)
• Identification, Tax Numbers, Bank Details

Instead of making multiple API calls, you can send one nested JSON structure containing all relevant data.

Key Entities and Relationships

Below are some of the commonly used entities that can be combined in deep payloads:

Hierarchy Example:
BusinessPartner
 ├── to_BusinessPartnerRole
 ├── to_BusinessPartnerAddress
 ├── to_Customer
 │     ├── to_CustomerCompany
 │     └── to_CustomerSalesArea
 └── to_Supplier
       ├── to_SupplierCompany
       └── to_SupplierPurchasingOrg

 

Example Scenarios

Here are some typical examples of deep payload combinations:

- Business Partner + Customer
- Business Partner + Supplier
- Business Partner + Bank Details
- Business Partner + Identification Details

 

Understanding Entity Relationship in API_BUSINES_PARTNER 

1. Open the API on SAP API Business Hub
   This is the best place to understand how Business Partner entities are structured.
   👉https://api.sap.com/api/API_BUSINESS_PARTNER/overview
   
   
2. Review the Entity Model or the $metadata
   The metadata file describes all entities, fields, and relationships used in the API.
   
   
3. Check the Metadata URL
   /sap/opu/odata/sap/API_BUSINESS_PARTNER/$metadata
   
   
4. Identify Navigation Properties
   Navigation properties show how entities are connected. Examples include:
      to_Customer
      to_Supplier
      to_BusinessPartnerAddress
      to_BusinessPartnerRole
   
   
5. Understand the Root Entity
   The main (parent) entity is A_BusinessPartner.
   All other entities are connected to it through navigation properties.

   

   

   
   
6. Child Entities Can Have Their Own Children
   For example:
   A_Customer is a child of A_BusinessPartner
   Under A_Customer, there are further children:
   
   
   
   
7. Key Considerations Before Designing Payload
   1. Mandatory Fields
      

      For Business Partner:

      • BusinessPartnerCategory (e.g., "1" = Person, "2" = Org)
      • LastName / OrganizationName1
      • Country
      • Language

      For Customer:

      • Customer (BP Number or empty for creation)
      • CompanyCode
      • ReconciliationAccount

       For Supplier:

      • PurchasingOrganization
      • OrderingCurrency
      
      
   2. Control Flags
      For deep insert:
      • "to_..." navigation properties must be included
      • Omit read-only fields (CreationDate, ChangedBy, etc.)
      
      

Step-by-Step: How to Prepare a Deep Payload

1. Identify the Root Entity - Always A_BusinessPartner for API_BUSINESS_PARTNER (Parent node)
2. Explore Metadata - via /sap/opu/odata/sap/API_BUSINESS_PARTNER/$metadata to see navigation properties
3. Build the Payload Structure - root = Business Partner, add nested structures for child entities
4. Prepare and Test Payloads in any third-party API testing tool or SAP Gateway Client (/IWFND/GW_CLIENT)

 

Example 1: Business Partner + Customer Creation 

In this example, a Business Partner and its associated Customer master data are created together using a single deep-create request.
This payload demonstrates how multiple dependent entities—such as business partner general data, Customer company code data, and Customer sales area data—can be submitted in one OData call.

{
  "BusinessPartnerCategory": "2",
  "OrganizationBPName1": "ABC Tech Pvt Ltd",
  "BusinessPartnerGrouping": "XXXX",
  "to_BusinessPartnerRole": [
    { "BusinessPartnerRole": "FLCU01" },
    { "BusinessPartnerRole": "FLCU00" }
  ],
  "to_BusinessPartnerAddress": [
    {
      "Country": "IN",
      "CityName": "Bangalore",
      "PostalCode": "XXXX",
      "StreetName": "MG Road",
      "HouseNumber": "XX",
      "Language": "EN",
      "to_EmailAddress": [
        {
          "EmailAddress": "info@XXX.com",
          "IsDefaultEmailAddress": true
        }
      ]
    }
  ],
  "to_Customer": {
    "CustomerAccountGroup": "XXXX",
    "to_CustomerCompany": [
      {"CompanyCode": "XXXX", "ReconciliationAccount": "XXXXXX"}
    ],
    "to_CustomerSalesArea": [
      {
        "SalesOrganization": "0001",
        "DistributionChannel": "01",
        "Division": "01",
        "CustomerPricingProcedure": "1",
        "PriceListType": "01"
      }
    ]
  }
}

Example 2: Business Partner + Supplier Creation

In this example, a Business Partner and its associated Supplier master data are created together using a single deep-create request. This payload demonstrates how multiple dependent entities—such as BP general data, Supplier company code data, and Supplier purchasing organization data—can be submitted in one OData call.

{
  "BusinessPartnerCategory": "2",
  "OrganizationBPName1": "XYZ Supplies Ltd",
  "BusinessPartnerGrouping": "XXXX",
  "SearchTerm1": "XYZ",
  "to_BusinessPartnerRole": [
    { "BusinessPartnerRole": "FLVN01" },
    { "BusinessPartnerRole": "FLVN00" }
  ],
  "to_BusinessPartnerAddress": [
    {
      "Country": "IN",
      "CityName": "Bangalore",
      "PostalCode": "XXXXXX",
      "StreetName": "MG Road",
      "HouseNumber": "XX",
      "Language": "EN"
    }
  ],
  "to_Supplier": {
    "SupplierAccountGroup": "XXXX",
    "to_SupplierCompany": [
      {
        "CompanyCode": "XXXX",
        "ReconciliationAccount": "XXXXXX"
      }
    ],
    "to_SupplierPurchasingOrg": [
      {
        "PurchasingOrganization": "0001",
        "PurchaseOrderCurrency": "INR"
      }
    ]
  }
}

Example 3: Business Partner + Bank/Identification

In this example, a Business Partner is created along with its associated bank account and identification details in a single deep-create request. This payload demonstrates how additional dependent entities, such as bank account assignments, identification numbers, and country-specific ID types, can be submitted together in a single OData call.

{
  "BusinessPartnerCategory": "2",
  "OrganizationBPName1": "ABC Tech Ltd",
  "BusinessPartnerGrouping": "XXXX",
  "to_BusinessPartnerBank": [
    {
      "BankCountryKey": "IN",
      "BankNumber": "XXXXXXXXXX",
      "BankAccount": "XXXXXXXXXX",
      "BankName": "Bank Name"
    }
  ]
}

Identification Details:
{
  "BusinessPartnerCategory": "2",
  "OrganizationBPName1": " ABC Tech Ltd ",
  "BusinessPartnerGrouping": "XXXX",
  "to_BuPaIdentification": [
    {
      "BPIdentificationType": "XXX",
      "BPIdentificationNumber": "XXXXXXXXXX",
      "ValidityStartDate": "2023-01-01T00:00:00",
      "ValidityEndDate": "9999-12-31T00:00:00"
    }
  ]
}

An alternate way of preparing a payload

Sometimes it isn't easy to write a Deep Payload from scratch because there are many parent–child entities. An easy method is to read an existing Business Partner and copy its structure to prepare your payload.

Here is how you can do it:

Step 1: Use a GET call with $expand to see the full structure

If you want to create a Business Partner along with Supplier details, Company Code details, or Purchasing Org details, you can first read an existing business partner record that already has those values. 

You do this using a GET call with $expand to include all related child entities. 

Example URI: 

/sap/opu/odata/sap/API_BUSINESS_PARTNER/A_BusinessPartner('XXXXXXXXXX') 

?$expand=to_Supplier,to_Supplier/to_SupplierCompany,to_Supplier/to_SupplierPurchasingOrg 

This reads the Business Partner along with: 

• Supplier Header 

• Supplier Company Code details 

• Supplier Purchasing Organization details 
  
  

Step 2: Copy the Response Payload Using Available Tools

For SAP S/4HANA Cloud Public Edition:

• SAP Business Accelerator Hub (API Hub) “Try Out” feature 

• Any third-party API testing tool 

• SAP API Sandbox 

• Any REST tool supported in your landscape 

For SAP S/4HANA Cloud Private Edition:

You can use the SAP Gateway Client (/IWFND/GW_CLIENT): 

• Execute the GET call 

• After receiving the response, choose “Use as Request” 

• The tool automatically copies the JSON body into the request editor 

Now you have a ready-made payload template. 

Step 3: Modify the Payload for Your POST Request 

After copying the response: 

• Remove key fields (like Business Partner number) 

• Remove read-only values (like CreatedBy, CreationDate) 

• Change the values to what you want to create 

• Keep only the nodes you need 

This approach makes your payload correct and aligned with metadata automatically. 

Why is this method useful?

This method is simple because:

• You don’t need to know the navigation properties
• You don’t have to build a JSON structure yourself
• You avoid mistakes in hierarchy
• You get a real working example from the system itself

Even someone new to the business partner API can follow this approach.

Below is a visual representation of the typical workflow while using the alternative approach to create a business partner record with a deep payload.

Testing and Validation

Use any API testing tool or SAP Gateway Client to test the Deep POST operation.

URL: /sap/opu/odata/sap/API_BUSINESS_PARTNER/A_BusinessPartner
Method: POST
Headers: Content-Type: application/json, Accept: application/json

Conclusion

To prepare any deep or complex payload:

• Read the parent–child structure from the metadata
• Identify which navigation properties are needed
• Build your JSON payload using the same hierarchy
• Use SAP API Business Hub as a reference for field names, structures, and samples

Deep POST (Deep Insert) allows you to create parent + child entities in a single API request. This approach simplifies integration, ensures consistency, and minimizes the number of API calls.