Acumatica Customization: The Ultimate Do's and Don'ts Guide

Acumatica's customization framework is one of its greatest strengths—but also one of its biggest risks when done incorrectly. Poorly designed customizations often lead to upgrade failures, performance issues, and long-term maintenance challenges. This guide compiles the most common mistakes developers make and provides clear guidance on how to avoid them.

Part 1: Critical Do's

✅ DO Use the "Usr" Prefix for Custom Fields

Custom columns added to Acumatica's standard tables must start with "Usr" – this is what tells the upgrade process to preserve them. Columns without the prefix may be removed during an upgrade.

// ✅ CORRECT
[PXDBString(50)]
[PXUIField(DisplayName = "UsrCustomField")]
public virtual string UsrCustomField { get; set; }

// ❌ WRONG - May be removed during upgrade
[PXDBString(50)]
[PXUIField(DisplayName = "CustomField")]
public virtual string CustomField { get; set; }

✅ DO Use the Validate Project Prefix Tool

Acumatica provides a built-in tool to validate that all new objects in your solution comply with naming conventions. Select File > Validate Project Prefix in the Customization Project Editor menu. This ensures:

• All new objects follow proper naming conventions
• Customizations remain upgrade-safe
• ISV certification requirements are met

✅ DO Follow Naming Conventions

Acumatica has specific naming conventions for tables (DACs) and columns (fields) :

✅ DO Use Development Environment First

Always conduct customization work in a separate development environment rather than directly in production. Acumatica recommends a three-environment workflow: development → staging → production .

✅ DO Use Version Control

Every customization should be developed using version control (Git or equivalent systems), with a dedicated repository and full commit history. Each commit should be tied to a specific requirement and represent a logical, reviewable change .

✅ DO Use Generic Event Handlers

Modern Acumatica development favors generic event handlers over classic ones—they're easier to declare, use, and validate in Visual Studio.

// ✅ RECOMMENDED - Generic handler
protected virtual void _(Events.RowSelected<SOOrder> e)
{
    // Business logic here
}

// ❌ LESS PREFERRED - Classic handler
protected virtual void SOOrder_RowSelected(PXCache sender, PXRowSelectedEventArgs e)
{
    // Business logic here
}

✅ DO Package All Database Changes in Customization Projects

All solution-specific database schema changes must be packaged into a customization project. SQL scripts are strictly prohibited unless they are provided as part of database upgrade scripts .

Part 2: Critical Don'ts

❌ DON'T Use PXDefault Without Proper PersistingCheck

The PXDefault attribute used without PersistingCheck = PXPersistingCheck.Nothing on custom fields defined in PXCacheExtension can prevent persisting of records to the database [citation:2].

// ❌ WRONG - Causes PX1030 warning/error
[PXDefault(0)]
public virtual int? UsrLineCounter { get; set; }

// ✅ CORRECT - With PersistingCheck
[PXDefault(0, PersistingCheck = PXPersistingCheck.Nothing)]
public virtual int? UsrLineCounter { get; set; }

// ✅ CORRECT - Alternative using PXUnboundDefault
[PXUnboundDefault]
public virtual bool? Selected { get; set; }

❌ DON'T Use .Result or .Wait() in Acumatica Code

Just like in standard ASP.NET Core, blocking on asynchronous code in Acumatica can cause deadlocks and thread-pool starvation. Always use await and propagate async all the way.

// ❌ WRONG - Can cause deadlocks
var result = service.GetDataAsync().Result;

// ❌ WRONG - Also dangerous
service.SaveDataAsync().Wait();

// ✅ CORRECT - Async all the way
var result = await service.GetDataAsync();

❌ DON'T Use ServiceLocator Pattern for Dependencies

In Acumatica 2026 R1, the framework has been refactored to support constructor-based dependency injection. The ServiceLocator pattern limits testability and makes plug-ins harder to maintain [citation:1].

// ❌ OLD - ServiceLocator pattern (limited testability)
protected async Task<HttpResponseMessage> ExecuteAsync(HttpRequestMessage request)
{
    using (var client = ServiceLocator.Current.GetInstance<IHttpClient>())
    {
        var response = await client.SendAsync(request);
        return response;
    }
}

// ✅ NEW - Constructor-based DI (2026 R1+)
public class MyPaymentPlugin : ICCProcessingPlugin
{
    private readonly IHttpClient _httpClient;

    public MyPaymentPlugin(IHttpClient httpClient)
    {
        _httpClient = httpClient;
    }

    protected async Task<HttpResponseMessage> ExecuteAsync(HttpRequestMessage request)
    {
        var response = await _httpClient.SendAsync(request);
        return response;
    }
}

❌ DON'T Modify Core Acumatica Code Directly

Never modify base Acumatica code directly—always use the extension model . Direct modifications will be lost during upgrades and can cause significant maintenance issues.

• Use PXGraphExtension for graph customizations
• Use PXCacheExtension for DAC extensions
• Use PXOverride for method overrides
• Use PXAction for custom actions

❌ DON'T Skip Documentation

Document everything throughout the customization process. Not only will this help with current projects, but it will also be invaluable for future modifications or troubleshooting .

• Maintain a Functional Specification Document (FSD) with screen-by-screen behavior, field logic, and edge cases
• Document all customizations in the Customization Project Editor
• Keep a changelog for all modifications

❌ DON'T Start Coding Without Requirements

Before estimating or designing anything, focus on discovery and validation :

• Which Acumatica version is in use?
• Are there out-of-the-box features that already solve part of the request?
• Is a hybrid approach (OOTB + targeted customization) possible?

Part 3: Best Practices Summary

Common Pitfalls Summary

Development Environment Configuration

To optimize your development experience, add these settings to your web.config file :

<configuration>
    <appSettings>
        <!-- Enable website debugging -->
        <add key="AutomationDebug" value="True" />
        
        <!-- Optimize startup time -->
        <add key="InstantiateAllCaches" value="False" />
        <add key="CompilePages" value="False" />
        
        <!-- Disable scheduler during development -->
        <add key="DisableScheduleProcessor" value="True" />
    </appSettings>
    
    <system.web>
        <compilation debug="true" />
    </system.web>
</configuration>

These settings enable page validation warnings, show automation steps, and optimize instance startup—saving significant development time .

The Bottom Line