Small and medium business | Business Central, N...

API POST request with deep inserts creates "unwanted" lines

(7) Share

Report

Posted on by CN-28080907-0

API POST request with deep inserts creates "unwanted" lines

Hi,

When performing multiple API Posts using the same payload to create Purchase Invoice with lines using deep inserts ended up creating "unwanted" additional lines. This to me is wrong, when the same POST request is executed, BC should just issue a duplicate error.

1) Create API pages for Purchase Header and Line (Document Type = Order)

2) POST request is executed with the following payload:
{
"documentType": "Order",
"no": "9011",
"buyFromVendorNo": "10000",
"yourReference": "VINV001",
"purchaseLines": [
{
"lineNo": 1,
"type": "Item",
"no": "1964-S",
"description": "TEST",
"quantity": 1
},
{
"lineNo": 2,
"type": "Item",
"no": "1964-S",
"description": "TEST",
"quantity": 2
}
]
}

3) The same Payload is executed again (This time, I would expect BC to issue and error, instead I get a 201)

4) When I check the Purchase Order in BC, this is what I see:

It seems any additional POST request that I execute to create Purchase Order 9011, will just keep appending lines to the Order.

The expected behaviour from this would be for BC to issue a duplicate error.

Categories:

Dynamics 365 Business Central

I have the same question (1)

All responses (5)

Answers (0)

Sort by

Suggested answer

Rishabh Kanaskar 6,219 Super User 2026 Season 1 on at

Like (10)

Report
Copy link

Link copied!

Hi,

This is expected behavior.

A POST with the same payload and "no" will update the existing document by adding lines instead of throwing a duplicate error.

If you want BC to block duplicates:
> First do a "GET" on the header by "no" to check if it already exists.
> If it does, either "PATCH" to update or return an error from your integration logic.
> Alternatively, implement a custom API page/codeunit that validates header existence and throws an error before inserting.

BC standard APIs don’t validate duplicate POST payloads by design.

Thanks

Rishabh

3 people found this reply helpful.

Was this reply helpful? Yes No
Suggested answer

Sahan Hasitha 2,683 on at

Like (5)

Report
Copy link

Link copied!

hi

When using Business Central APIs with deep inserts, each POST request is treated as a new create action, which means sending the same payload multiple times will insert additional lines rather than returning a duplicate error. This behavior is by design, as the API does not automatically validate against duplicate payloads or enforce idempotency. To avoid unwanted duplicate lines, you should implement idempotency in your integration logic—for example, by checking if the document number already exists before posting, or by using PATCH for updates instead of POST for inserts. Another approach is to introduce a unique identifier (such as idempotency-key or a custom external reference field) that you validate before creating the order. Without such safeguards, repeated POST calls will continue to generate new lines.

3 people found this reply helpful.

Was this reply helpful? Yes No
Suggested answer

Sumit Singh 11,761 Super User 2026 Season 1 on at

Like (3)

Report
Copy link

Link copied!
Hi,
If you send the same POST request multiple times, the system will create something new each time instead of rejecting it as a duplicate.
Try below options:-
1) Enforce business keys in your custom API

Header: set ODataKeyFields = "Document Type","No." (or a custom integrationId).

Lines: set ODataKeyFields = "Document Type","Document No.","Line No." and AutoSplitKey = false.
→ A second POST with the same header/lines now returns a duplicate error instead of appending.
2) Use upsert flow with a client key

POST once with a unique integrationId; for retries use PATCH to that resource and include If-Match (ETag).
3) Read‑before‑write

GET by no (or external reference); create only if not found.

Tip: Use standard line numbering (10,000, 20,000, …) or disable AutoSplitKey; otherwise BC silently renumbers and you can’t detect duplicates on lines.
Useful Microsoft docs

Create purchaseOrders (API v2.0) – request/response semantics for POST (201 Created).
Create purchaseOrders [Create pur...soft Learn]

API v2.0 overview & reference – how BC APIs are identified, extended, and constrained.
API (v2.0) for Business Central [API (v2.0)...entral ...]

Developing a custom API – defining ODataKeyFields, parts, and behavior.
Develop a custom API [Developing...soft Learn]

ETags / If‑Match – BC endpoints require ETag on updates (optimistic concurrency).
Update items (If-Match) [Update ite...soft Learn]

Response created with the help of Co-Pilot. Please mark “Verified” if it helps.

Was this reply helpful? Yes No
Suggested answer

YUN ZHU 99,966 Super User 2026 Season 1 on at

Like (3)

Report
Copy link

Link copied!

As other experts have mentioned, you should use Patch instead of Post. Hopefully the information below can give you some hints.

https://yzhums.com/6117/#toc16

Thanks.

ZHU

Was this reply helpful? Yes No
Suggested answer

Jeffrey Bulanadi 9,114 Super User 2026 Season 1 on at

Like (0)

Report
Copy link

Link copied!
Hi,

Deep inserts can feel intuitive until you hit this exact scenario ,where repeated POSTs don’t trigger a duplicate error but instead append new lines. I totally get why this feels wrong, especially when you're expecting idempotent behavior from your API calls.

Here’s what’s happening under the hood: BC’s standard API behavior treats each POST as a new transaction unless you explicitly check for existing records. The system doesn’t validate whether the document number already exists ,it simply inserts the header and appends the lines, even if the payload is identical.

To avoid this, here’s what I’d recommend:

Implement a pre-check before issuing the POST. Use a GET request to verify if the document number already exists. If it does, either skip the POST or switch to a PATCH or PUT depending on your update logic.

Use idempotency keys or a custom field like externalReferenceId to track whether a payload has already been processed. This gives you a way to reject duplicates at the application level.

Add validation logic in the API page triggers. You can use OnInsertRecord or OnAfterGetRecord on the header page to check if the document already exists and raise an error before lines are inserted. This is especially useful if you want to roll back the entire transaction.

Consider using DelayedInsert = true on your API page definitions. This gives you more control over when records are committed and lets you validate the payload before finalizing the insert.

Track line uniqueness using a composite key or external line reference. If your lines are meant to be unique, you’ll need to enforce that either through validation or by rejecting repeated line numbers.

Helpful Reference
How to do deep inserts into a custom API in BC? — mibuso.com
Solved: Custom Api - Deep Insert
microsoft dynamics - How to deep inserts in BC with a custom API? - Stack Overflow
API (v2.0) for Dynamics 365 BC - BC | Microsoft Learn

If you find this helpful, feel free to mark this as the suggested or verified answer.

Cheers
Jeffrey

Was this reply helpful? Yes No