Business Central AL Extensions: Customization, Event Architecture, and Custom API Development

TL;DR

• Bottom line: AL extensions are the only supported customization model for Business Central SaaS. They let you add custom tables, pages, codeunits, reports, and API pages without modifying the base application. Custom API pages expose your data as OData v4 / REST endpoints that external systems can consume.
• Key limit: 600 API requests/min in Production, 300/min in Sandbox (combined OData + SOAP). Individual requests time out at 10 minutes (HTTP 504). [src3]
• Watch out for: You cannot extend existing standard API pages — you must create entirely new API page objects. Also, the event subscriber model means you must understand the publisher-subscriber pattern to hook into standard business logic without breaking upgrades. [src1, src2]
• Best for: Building custom integrations, adding business logic to standard processes via events, exposing custom data through REST/OData endpoints, and publishing reusable apps to AppSource. [src1]
• Authentication: Microsoft Entra ID (Azure AD) OAuth 2.0 for SaaS — use Client Credentials flow for service-to-service (S2S) integrations; Authorization Code flow for user-context apps. [src5]

System Profile

Microsoft Dynamics 365 Business Central is a cloud-first ERP for small and mid-sized businesses. The AL (Application Language) extension model replaced the legacy C/AL development model starting with Business Central v14 (2019). All customizations in Business Central SaaS must be delivered as AL extensions — direct code modification is not possible. Extensions follow an additive-only model: you can add new objects (tables, pages, codeunits, queries, reports, API pages) and extend existing objects (table extensions, page extensions, enum extensions), but you cannot delete or directly modify base application code. The event architecture (Business Events, Integration Events, Trigger Events) provides hooks into standard logic. Custom API pages let you expose extension data as OData v4 endpoints that conform to Business Central's standard REST API pattern. [src1, src2]

API Surfaces & Capabilities

Business Central exposes multiple API surfaces. AL extensions can create custom API pages that appear alongside the standard API v2.0 endpoints. [src1, src2, src3]

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits

AL Extension Operational Limits

Authentication

Business Central SaaS uses Microsoft Entra ID (formerly Azure AD) for all authentication. The choice of flow depends on whether the integration needs user context. [src5]

Authentication Gotchas

• S2S apps cannot use SUPER permission set: Create a custom permission set with exactly the permissions needed. [src5]
• Client Credentials flow requires explicit BC configuration: Registering in Entra ID alone is not enough — you must add the app's Client ID on the "Microsoft Entra Applications" page in Business Central. [src5]
• Token audience must match: The OAuth token must target https://api.businesscentral.dynamics.com (SaaS) or the on-premises URL. Mismatched audience causes hard-to-debug auth failures. [src5]
• Multi-environment setups: Each BC environment (production, sandbox) requires separate Entra app configuration. Tokens for one environment do not work on another. [src5]

Constraints

• Extensions cannot modify base code — all customization must be additive: new objects, object extensions, or event subscribers. You cannot delete fields, remove validation logic, or change base table structures. [src1]
• Cannot extend standard API pages — Microsoft blocks extending API page objects. To add custom fields to a standard entity's API, create a new custom API page. [src2]
• Breaking schema changes require upgrade codeunits — once published and synchronized, subsequent versions must have backward-compatible schemas or include upgrade codeunit logic. [src1, src7]
• AppSource mandatory requirements — reserved prefix/suffix, DataClassification on every Normal field, mandatory test codeunits, alignment with BC release cadence. [src7]
• Per-tenant extension limit — maximum 75 per-tenant extensions per environment. AppSource apps do not count against this. [src1]
• Event subscriber execution order not guaranteed — when multiple extensions subscribe to the same event, execution order is undefined. [src4]

Integration Pattern Decision Tree

START — User needs to integrate with or customize Business Central
|-- What's the goal?
|   |-- Expose custom data as API endpoint
|   |   |-- Custom table? --> Create table + API page (PageType = API) [src2]
|   |   |-- Extend standard entity? --> Table extension + new custom API page [src2]
|   |   |-- Complex business logic? --> API page + codeunit with business logic
|   |-- Hook into standard business process
|   |   |-- Before/after standard operation? --> Event subscriber (Integration/Business Event) [src4]
|   |   |-- Validate data before insert/modify? --> OnBeforeInsertEvent / OnBeforeModifyEvent [src4]
|   |   |-- React to data changes externally? --> Webhook subscription on entity
|   |-- Consume external API from BC
|   |   |-- Synchronous call needed? --> HttpClient in AL codeunit [src1]
|   |   |-- Async/scheduled? --> Job Queue + HttpClient [src1]
|   |-- Bulk data integration
|   |   |-- < 1,000 records? --> Standard API v2.0 with pagination
|   |   |-- > 1,000 records? --> Custom API page with optimized queries + batch processing
|   |   |-- > 100,000 records? --> Configuration Packages or RapidStart
|-- Which direction?
|   |-- Inbound (external writes to BC) --> Custom API page or standard API v2.0
|   |-- Outbound (BC pushes to external) --> Event subscriber + HttpClient callout
|   |-- Bidirectional --> Design conflict resolution; use SystemModifiedAt for delta sync
|-- Error tolerance?
    |-- Zero-loss --> Idempotency (check before insert) + error logging table
    |-- Best-effort --> Try/catch with Notification or Error logging

Quick Reference

Step-by-Step Integration Guide

1. Set up AL development environment

Install Visual Studio Code with the AL Language extension. Create a new AL project using the AL: Go! command. Configure launch.json and app.json with correct runtime version and dependencies. [src1]

// app.json — key properties
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "My Custom Integration",
  "publisher": "MyCompany",
  "version": "1.0.0.0",
  "runtime": "15.0",
  "target": "Cloud",
  "application": "25.0.0.0",
  "platform": "25.0.0.0",
  "dependencies": [],
  "features": ["TranslationFile", "GenerateCaptions"]
}

Verify: AL: Download Symbols (Ctrl+Shift+P) completes successfully.

2. Create a custom table and table extension

Define custom tables or extend existing tables with new fields using table extensions. [src1]

// Custom table for integration data
table 50100 "My Integration Data"
{
    DataClassification = CustomerContent;
    Caption = 'My Integration Data';

    fields
    {
        field(1; "Entry No."; Integer)
        {
            DataClassification = SystemMetadata;
            AutoIncrement = true;
        }
        field(2; "External ID"; Code[50])
        {
            DataClassification = CustomerContent;
        }
        field(3; "Description"; Text[250])
        {
            DataClassification = CustomerContent;
        }
        field(4; "Amount"; Decimal)
        {
            DataClassification = CustomerContent;
        }
    }

    keys
    {
        key(PK; "Entry No.") { Clustered = true; }
        key(ExternalID; "External ID") { }
    }
}

Verify: Extension compiles without errors (Ctrl+Shift+B).

3. Create a custom API page

Define an API page to expose your table as an OData v4 / REST endpoint. Set the required API properties. [src2]

page 50100 "My Integration Data API"
{
    PageType = API;
    APIPublisher = 'mycompany';
    APIGroup = 'integration';
    APIVersion = 'v2.0';
    EntityName = 'integrationData';
    EntitySetName = 'integrationData';
    EntityCaption = 'Integration Data';
    EntitySetCaption = 'Integration Data';
    SourceTable = "My Integration Data";
    ODataKeyFields = SystemId;
    DelayedInsert = true;
    Extensible = false;

    layout
    {
        area(Content)
        {
            repeater(Group)
            {
                field(id; Rec.SystemId) { Editable = false; }
                field(externalId; Rec."External ID") { }
                field(description; Rec.Description) { }
                field(amount; Rec.Amount) { }
            }
        }
    }
}

Verify: After publishing, call GET /api/mycompany/integration/v2.0/companies({companyId})/integrationData to confirm the endpoint returns data.

4. Implement event subscribers

Subscribe to Integration Events or Business Events to hook into standard processes. [src4]

codeunit 50100 "My Event Subscribers"
{
    [EventSubscriber(ObjectType::Codeunit, Codeunit::"Sales-Post",
        OnAfterPostSalesDocument, '', false, false)]
    local procedure OnAfterPostSalesDocument(
        var SalesHeader: Record "Sales Header";
        var GenJnlPostLine: Record "Gen. Journal Line";
        SalesShptHdrNo: Code[20];
        RetRcpHdrNo: Code[20];
        SalesInvHdrNo: Code[20];
        SalesCrMemoHdrNo: Code[20])
    var
        IntegrationData: Record "My Integration Data";
    begin
        IntegrationData.Init();
        IntegrationData."External ID" := SalesInvHdrNo;
        IntegrationData.Description := 'Posted Sales Invoice';
        IntegrationData.Amount := SalesHeader."Amount Including VAT";
        IntegrationData.Insert(true);
    end;
}

Verify: Post a sales invoice, then query the custom API endpoint to confirm the record was created.

5. Register S2S authentication

Register a Microsoft Entra ID application, configure it in Business Central, and obtain OAuth tokens. [src5]

# Obtain access token via Client Credentials flow
curl -X POST "https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}" \
  -d "scope=https://api.businesscentral.dynamics.com/.default" \
  -d "grant_type=client_credentials"

# Call custom API endpoint
curl -X GET "https://api.businesscentral.dynamics.com/v2.0/{tenant_id}/{environment}/api/mycompany/integration/v2.0/companies({company_id})/integrationData" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"

Verify: The API returns a JSON array of records with HTTP 200.

6. Implement error handling and retry logic

Handle HTTP 429 (rate limit) and 504 (timeout) with exponential backoff. [src3]

import requests
import time

def bc_api_request(method, url, token, data=None, max_retries=5):
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
    if method in ("PATCH", "DELETE"):
        get_resp = requests.get(url, headers=headers)
        if get_resp.ok:
            headers["If-Match"] = get_resp.headers.get("ETag", "*")

    for attempt in range(max_retries):
        response = requests.request(method, url, headers=headers, json=data)
        if response.status_code in (200, 201, 204):
            return response.json() if response.content else None
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
            time.sleep(retry_after)
            continue
        if response.status_code == 504:
            time.sleep(min(2 ** attempt * 5, 120))
            continue
        try:
            msg = response.json().get("error", {}).get("message", response.text)
        except Exception:
            msg = response.text
        raise Exception(f"BC API error {response.status_code}: {msg}")
    raise Exception("Max retries exceeded")

Verify: Test with an invalid endpoint to confirm error parsing returns a readable message.

Code Examples

AL: Custom API page with bound action

page 50101 "Integration Data Action API"
{
    PageType = API;
    APIPublisher = 'mycompany';
    APIGroup = 'integration';
    APIVersion = 'v2.0';
    EntityName = 'integrationAction';
    EntitySetName = 'integrationActions';
    EntityCaption = 'Integration Action';
    EntitySetCaption = 'Integration Actions';
    SourceTable = "My Integration Data";
    ODataKeyFields = SystemId;
    Extensible = false;

    layout
    {
        area(Content)
        {
            repeater(Group)
            {
                field(id; Rec.SystemId) { Editable = false; }
                field(externalId; Rec."External ID") { }
                field(status; Rec.Status) { Editable = false; }
            }
        }
    }

    [ServiceEnabled]
    procedure ProcessRecord(var ActionContext: WebServiceActionContext)
    var
        IntegrationMgt: Codeunit "My Integration Management";
    begin
        IntegrationMgt.ProcessIntegrationRecord(Rec);
        ActionContext.SetObjectType(ObjectType::Page);
        ActionContext.SetObjectId(Page::"Integration Data Action API");
        ActionContext.AddEntityKey(Rec.FieldNo(SystemId), Rec.SystemId);
        ActionContext.SetResultCode(WebServiceActionResultCode::Updated);
    end;
}

PowerShell: Authenticate and query custom API

# Install: Install-Module MSAL.PS -Scope CurrentUser
$tenantId = "your-tenant-id"
$clientId = "your-client-id"
$clientSecret = "your-client-secret" | ConvertTo-SecureString -AsPlainText -Force
$environment = "production"

$tokenParams = @{
    ClientId     = $clientId
    TenantId     = $tenantId
    ClientSecret = $clientSecret
    Scopes       = "https://api.businesscentral.dynamics.com/.default"
}
$token = Get-MsalToken @tokenParams

$headers = @{
    Authorization = "Bearer $($token.AccessToken)"
    Accept        = "application/json"
}
$baseUrl = "https://api.businesscentral.dynamics.com/v2.0/$tenantId/$environment"
$companies = Invoke-RestMethod -Uri "$baseUrl/api/v2.0/companies" -Headers $headers
$companyId = $companies.value[0].id

$data = Invoke-RestMethod `
    -Uri "$baseUrl/api/mycompany/integration/v2.0/companies($companyId)/integrationData" `
    -Headers $headers

$data.value | Format-Table externalId, description, amount, status

cURL: Quick API connectivity test

# Get token
TOKEN=$(curl -s -X POST \
  "https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token" \
  -d "client_id={client_id}&client_secret={client_secret}&scope=https://api.businesscentral.dynamics.com/.default&grant_type=client_credentials" \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['access_token'])")

# List companies
curl -s "https://api.businesscentral.dynamics.com/v2.0/{tenant_id}/{environment}/api/v2.0/companies" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" | python3 -m json.tool

# Query custom API endpoint
curl -s "https://api.businesscentral.dynamics.com/v2.0/{tenant_id}/{environment}/api/mycompany/integration/v2.0/companies({company_id})/integrationData?\$top=10" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" | python3 -m json.tool

# Create a record
curl -X POST "https://api.businesscentral.dynamics.com/v2.0/{tenant_id}/{environment}/api/mycompany/integration/v2.0/companies({company_id})/integrationData" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"externalId": "EXT-001", "description": "Test record", "amount": 150.00}'

Data Mapping

Field Mapping Reference

Data Type Gotchas

• Enum values in API are caption strings, not ordinals: Use the English caption value (e.g., "Open", not 0) when filtering or setting enum fields. [src2]
• DateTime timezone handling: BC stores all DateTime values in UTC. The API returns them with the UTC offset. Always parse the offset or convert to UTC. [src1]
• ETag required for PATCH and DELETE: Every PATCH or DELETE must include an If-Match header with the record's current ETag. Omitting it returns HTTP 412 Precondition Failed. [src2]
• SystemId vs. "No." fields: API pages should use SystemId (GUID) as the key via ODataKeyFields, not the traditional "No." field. [src2]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Extension upgrade breaks event subscribers: When BC is updated (e.g., BC26 to BC27), event signatures may change, causing subscriber compilation failures. Fix: Pin runtime version and application dependency. Test against preview environment before each release wave. [src1, src6]
• Custom API page returns 404 after deployment: Extension is published but API page not visible due to naming conflicts or incomplete installation. Fix: Verify extension is installed (not just published). Check APIPublisher/APIGroup naming conflicts. [src2]
• Rate limit exhaustion in batch integrations: Bulk sync sending individual calls quickly hits 600/min. Fix: Throttle to ~500/min with backoff. Use $batch OData requests where supported. [src3]
• ETag-related update failures: Multiple processes updating same records cause 409/412 errors. Fix: Always GET record first, extract ETag, PATCH with If-Match. On conflict, re-read and retry. [src2]
• Event subscriber infinite loops: A subscriber modifying a record triggers the same event recursively. Fix: Use a static boolean flag to detect re-entry. Design subscribers to be idempotent. [src4]

Anti-Patterns

Wrong: Directly modifying base application tables

// BAD — this is impossible in AL extensions and causes compilation errors
table 18 Customer
{
    // Cannot redefine base objects
    fields
    {
        field(50100; "My Custom Field"; Text[100]) { }
    }
}

Correct: Use table extensions to add fields

// GOOD — extends the base Customer table without modifying it
tableextension 50100 "Customer Extension" extends Customer
{
    fields
    {
        field(50100; "My Custom Field"; Text[100])
        {
            DataClassification = CustomerContent;
            Caption = 'My Custom Field';
        }
    }
}

Wrong: Trying to extend a standard API page

// BAD — API pages cannot be extended; causes compilation error
pageextension 50100 "Customer API Ext" extends "Customer API"
{
    // NOT ALLOWED by design
}

Correct: Create a new custom API page for extended data

// GOOD — new API page that includes base + custom fields
page 50102 "Customer Extended API"
{
    PageType = API;
    APIPublisher = 'mycompany';
    APIGroup = 'custom';
    APIVersion = 'v2.0';
    EntityName = 'customerExtended';
    EntitySetName = 'customersExtended';
    EntityCaption = 'Customer Extended';
    EntitySetCaption = 'Customers Extended';
    SourceTable = Customer;
    ODataKeyFields = SystemId;
    Extensible = false;

    layout
    {
        area(Content)
        {
            repeater(Group)
            {
                field(id; Rec.SystemId) { Editable = false; }
                field(number; Rec."No.") { Editable = false; }
                field(displayName; Rec.Name) { }
                field(myCustomField; Rec."My Custom Field") { }
            }
        }
    }
}

Wrong: Using ToBeClassified DataClassification

// BAD — blocks AppSource validation and is a compliance risk
field(50100; "Customer Tax ID"; Text[20])
{
    DataClassification = ToBeClassified;
}

Correct: Always set proper DataClassification

// GOOD — explicit classification for GDPR/compliance
field(50100; "Customer Tax ID"; Text[20])
{
    DataClassification = CustomerContent;
    Caption = 'Customer Tax ID';
}

Common Pitfalls

• Not reserving a prefix/suffix for AppSource: Every object name and field name must use a reserved prefix or suffix. #1 cause of AppSource validation failures. Fix: Register your prefix/suffix with Microsoft before development. [src7]
• Hardcoding runtime version too high: Setting "runtime": "15.0" means the extension only works on BC27+. Fix: Set runtime to the lowest version supporting the AL features you need. [src6]
• Ignoring upgrade codeunits: Removing or renaming fields without an upgrade codeunit causes data loss during upgrade. Fix: Always write upgrade codeunits for schema changes. [src1]
• Not handling the "Companies" wrapper in API URLs: Every BC API call must include /companies({companyId})/. Fix: Query /api/v2.0/companies first to get the company ID. [src2]
• Heavy logic in event subscribers: Multiple extensions with heavy subscribers slow down base operations. Fix: Keep subscribers lightweight. Queue heavy work to Job Queue entries. [src4, src8]
• Using OnRun trigger for API logic: OnRun is for manual execution, not API-callable logic. Fix: Use named procedures with [ServiceEnabled] attribute. [src2]

Diagnostic Commands

# Check available API endpoints (list companies)
curl -s "https://api.businesscentral.dynamics.com/v2.0/{tenant_id}/{environment}/api/v2.0/companies" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

# Test authentication (should return 200)
curl -s -o /dev/null -w "%{http_code}" \
  "https://api.businesscentral.dynamics.com/v2.0/{tenant_id}/{environment}/api/v2.0/companies" \
  -H "Authorization: Bearer $TOKEN"

# Check if custom API page is registered
curl -s "https://api.businesscentral.dynamics.com/v2.0/{tenant_id}/{environment}/api/mycompany/integration/v2.0/companies({company_id})/integrationData?\$top=1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

# Verify extension is installed (Automation API)
curl -s "https://api.businesscentral.dynamics.com/v2.0/{tenant_id}/{environment}/api/microsoft/automation/v2.0/companies({company_id})/extensions?\$filter=displayName eq 'My Custom Integration'" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

# Check OData metadata for custom endpoint
curl -s "https://api.businesscentral.dynamics.com/v2.0/{tenant_id}/{environment}/api/mycompany/integration/v2.0/\$metadata" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/xml"

Version History & Compatibility

Deprecation Policy

Microsoft follows a "Modern Lifecycle" policy: each release wave is supported until the next two waves are GA (~12 months). API v1.0 is deprecated in favor of v2.0. C/AL is fully deprecated — AL extensions are the only supported path. Microsoft provides at least one release wave notice before removing deprecated features. [src1, src6]

When to Use / When Not to Use

Important Caveats

• AL extension development requires a Business Central developer license or a production/sandbox environment with development permissions. The VS Code extension is free, but publishing requires licensing. [src1]
• Sandbox environments have lower API rate limits (300/min vs 600/min) and may not reflect production performance. [src3]
• The extension model is additive-only — you cannot remove functionality. To hide standard behavior, hide UI elements and use events to bypass logic. [src1]
• AppSource certification has strict requirements beyond code quality: telemetry, privacy policy, support availability, and release cadence alignment. Plan for 4-8 weeks validation. [src7]
• Microsoft releases two major BC updates per year (Wave 1 April, Wave 2 October). Each may change event signatures. Budget for testing and updating extensions with each wave. [src1, src6]