Sales order creation via sales management API fails with missing customer reference error after customer entity migration

ERP Microsoft Dynamics 365
, , , , , , , ,
1

We’re experiencing failures when creating sales orders through the Sales Management API in D365 Finance & Operations 10.0.41. After migrating customer master data from our legacy system last month, API calls to create new orders consistently return a 400 error with “Customer reference not found” even though the customer exists in the system.

The API payload structure we’re using:

{
  "customerId": "CUST-10045",
  "orderDate": "2025-03-15",
  "items": [{"productId": "P-200", "quantity": 10}]
}

The customer entity was successfully migrated and we can create orders manually through the UI without issues. Our integration was working perfectly before the migration. The sales order endpoint seems to require something additional that wasn’t needed previously. Has anyone encountered this after a customer data migration? What reference field might we be missing in our API calls?

2

Check your data entity mappings in the Data Management workspace. When you migrated customer data, did you use the CustomersV3 entity or a custom entity? The Sales Management API expects specific field mappings that align with the standard CustTable structure. If your migration used non-standard field mappings, the API won’t recognize the customer references even though they display correctly in the UI. I’d recommend running a test query through the OData endpoint to see exactly how your customer records are structured post-migration.

3

I’m wondering if this is related to the customer party number versus customer account distinction. After migration, your customers might have new party records created in the global address book. The API payload needs to reference the correct identifier. Try adding the “dataAreaId” field to specify the legal entity explicitly, especially if you’re working in a multi-company setup.

4

Looking at your payload structure, I can see you’re missing the CustomerAccount field which is mandatory after the customer entity migration you performed. Here’s what’s happening:

Customer Entity Migration Issue: When you migrated customer master data, the system created new internal references in the CustTable. Your legacy “customerId” field (CUST-10045) was likely stored as an external reference or alternate identifier, but the Sales Management API requires the actual CustomerAccount value from the AccountNum field.

API Payload Missing Reference: Your current payload uses “customerId” which isn’t a recognized field in the standard Sales Order endpoint. You need to use “CustomerAccount” instead. Additionally, you should include the “dataAreaId” to specify the legal entity context.

Updated payload structure:

{
  "dataAreaId": "USMF",
  "CustomerAccount": "US-001",
  "OrderDate": "2025-03-15",
  "lines": [{"ItemNumber": "P-200", "SalesQty": 10}]
}

Sales Order Endpoint Requirements: The SalesOrderHeaderV2 entity (which the API uses) expects PascalCase field names and the exact CustomerAccount value from your CustTable. To find the correct account numbers, query your customer data:

SELECT AccountNum, CustomerAccount, Name
FROM CustTable
WHERE <your legacy ID field> = 'CUST-10045'

If your migration preserved the legacy IDs in a custom field, you’ll need to either:

  1. Create a mapping table to translate legacy IDs to D365 AccountNum values
  2. Modify your integration to query the customer first using the CustomersV3 OData endpoint, then use the returned AccountNum in your sales order creation
  3. Update your source system to use the new D365 customer account numbers

Additional Considerations: Ensure your API user has the “Maintain sales orders” privilege and that the customer accounts are active with valid credit limits. The endpoint also requires the InvoiceAccount field if it differs from the ordering customer account. Test with the Data Management REST API endpoint first to validate your field mappings before moving to production integration.