Business Central 2024 Wave 1 (BC24) might break your API integrations!

A subtle change in default behaviour between BC23 and B24 might break your API integrations if you rely on Enum fields displaying the value of the fields. Check out the video:

https://youtu.be/600q1uTMIuk

Business Central 2024 Wave 1 (BC24) is rolling out, and while it brings exciting features like Copilot, there’s a breaking change that’s catching many people off guard: the default behavior for how enum and option values are returned in API responses has changed. In this video, Erik demonstrates the problem, shows how to work around it, and shares his thoughts on Microsoft’s approach to this transition.

The Problem: Changed Default Schema Version

Up until and including BC23, if you did not specify a schema version in your API calls, Business Central would default to version 1.0 behavior. In BC24, Microsoft changed this default to version 2.0. This seemingly small change has significant consequences—particularly for how option fields and enums are returned in API responses.

Fields like the line type on a sales line (Account, Item, etc.), VAT calculation type, prepayment VAT calculation type, and many other option/enum fields throughout Business Central are all affected. The result: on Friday your API returned human-readable captions, and on Monday after the weekend upgrade to BC24, the same API returns encoded enum names instead.

Demonstrating the Change

To illustrate the issue, Erik created a simple custom API page that exposes various enum and option fields from the Sales Line table. The same app was deployed to both a BC23 and a BC24 environment:

page 50140 APITest
{
    APIGroup = 'group';
    APIPublisher = 'hougaard';
    APIVersion = 'v2.0';
    ApplicationArea = All;
    Caption = 'apiTest';
    DelayedInsert = true;
    EntityName = 'salesheader';
    EntitySetName = 'salesheaders';
    PageType = API;
    SourceTable = "Sales Line";

    layout
    {
        area(content)
        {
            repeater(General)
            {
                field(documentNo; Rec."Document No.")
                {
                    Caption = 'Document No.';
                }
                field(documentType; Rec."Document Type")
                {
                    Caption = 'Document Type';
                }
                field("type"; Rec."Type")
                {
                    Caption = 'Type';
                }
                field(subtype; Rec.Subtype)
                {
                    Caption = 'Subtype';
                }
                field(vatCalculationType; Rec."VAT Calculation Type")
                {
                    Caption = 'VAT Calculation Type';
                }
                field(prepmtVATCalcType; Rec."Prepmt. VAT Calc. Type")
                {
                    Caption = 'Prepmt. VAT Calc. Type';
                }
                field(itemReferenceType; Rec."Item Reference Type")
                {
                    Caption = 'Item Reference Type';
                }
                field(icPartnerRefType; Rec."IC Partner Ref. Type")
                {
                    Caption = 'IC Partner Ref. Type';
                }
            }
        }
    }
}

This page deliberately includes a mix of fields backed by enums (like VAT Calculation Type, Type, and Item Reference Type) and traditional options (like Subtype), which behave differently under the new default.

BC23 Response (Schema Version 1.0 Default)

On BC23, the API returns human-readable caption values as expected:

  • vatCalculationType: "Sales Tax"
  • prepmtVATCalcType: "Normal VAT"
  • type: "Item"
  • Blank values appear as empty strings

This is the behavior that has been in place for a long time and that existing integrations rely on.

BC24 Response (Schema Version 2.0 Default)

On BC24, with no changes to the API call or the API page code, the same request now returns encoded enum names instead of captions:

  • Spaces become _x0020_ (Unicode encoding)
  • Slashes and other non-7-bit ASCII characters get similarly encoded
  • vatCalculationType: "Sales_x0020_Tax" instead of "Sales Tax"
  • The values returned are the enum member names rather than the enum captions

An interesting observation: traditional option fields (like Subtype) still return their old values—the change specifically affects enum fields. However, even option fields with spaces in their values will have those spaces encoded.

The Workaround: Specify the Schema Version

The fix is straightforward. You can explicitly request the schema version in your API URL by adding a query parameter:

To get the old behavior (version 1.0):

https://your-bc-url/api/hougaard/group/v2.0/salesheaders?$schemaversion=1.0

To explicitly request the new behavior (version 2.0):

https://your-bc-url/api/hougaard/group/v2.0/salesheaders?$schemaversion=2.0

This parameter works in both directions—you can request version 2.0 behavior on a BC23 environment, and you can request version 1.0 behavior on a BC24 environment. The key difference is simply what happens when you don’t specify anything.

Erik’s Take: The Burden Is on the Wrong Users

Erik acknowledges that there’s a valid case for returning enum names as unique identifiers instead of captions (which can vary by language). However, he feels strongly that the burden of complexity has been placed on the wrong set of users:

  • Developers who want the new encoded values are likely sophisticated enough to add $schemaversion=2.0 to their API calls.
  • Users who suddenly get broken integrations and need the old behavior may have a much harder time figuring out what happened and how to fix it.

By changing the default rather than requiring opt-in, Microsoft has put the troubleshooting burden on the group least equipped to handle it.

This Was Documented (But Who Reads Everything?)

To be fair, this change was not a complete surprise—if you happened to read the right documentation pages:

  1. There’s a page on Microsoft Learn called “Transitioning from API version one to API version two” that documents this behavior change at the bottom of the page.
  2. The deprecated features list for Business Central includes an entry for “Schema version for custom API change default” that clearly describes the change.

The practical problem, of course, is that environments get upgraded over weekends, and not everyone has read every single page of Microsoft documentation. Even Erik admits he probably read about it at some point and then forgot.

Summary

If your API integrations broke after upgrading to Business Central 2024 Wave 1 (BC24), here’s what you need to know:

  • The default API schema version changed from 1.0 to 2.0
  • Enum fields now return encoded member names instead of human-readable captions by default
  • Spaces become _x0020_, slashes and special characters are similarly encoded
  • Traditional option fields are less affected, but enums are significantly impacted
  • Quick fix: Add ?$schemaversion=1.0 to your API URLs to restore the previous behavior
  • Long-term: Consider updating your integrations to handle the version 2.0 format, as version 1.0 behavior may eventually be removed

This is a great reminder to review Microsoft’s deprecated features list before major upgrades—and to always explicitly specify schema versions in your API calls rather than relying on defaults that can change.

Picture of hougaard

hougaard