Acumatica (v23) - Onboarding Requirements [Information]

This article describes the setup requirements for the techSHIP Acumatica (v23) plugin. 

NOTE: This article is for the Acumatica v23 plugin. For the deprecated plugin version, see: Acumatica - Onboarding Requirements [Information].

This article is divided into the following sections:

1. Configuring Plugin Parameters
   1. Required
   2. Optional
2. Acumatica Endpoint Requirements
3. Other Considerations
   
   

I. CONFIGURING PLUGIN PARAMETERS

i. Required

When onboarding or adding a new Acumatica portal, you must provide and verify the following information (highlighted in red in the plugin configuration screenshot):

• Acumatica username
• Acumatica password
• Acumatica update username
• Acumatica update password
• Acumatica service URL
• Acumatica endpoint
  
  
  NOTE: The Acumatica REST endpoint used by techSHIP must follow this format:
  https://<acumatica-site>/entity/<EndpointName>/<Version>/
  Example: https://acumatica.example.com/entity/Techship/23.200.001/

  
  

   

  WARNING: The techSHIP Acumatica integration is currently tested and validated up to Acumatica version 23.200.001(Typically, Techship/[AcumaticaVersion]). Custom endpoints must be created against this version to ensure compatibility.

  
  

  
  

ii. Optional

The following parameters are optional (highlighted in blue in the plugin configuration screenshot):

• Acumatica Company 

• Acumatica Tenant 

• Acumatica Branch 

• Acumatica default box type (e.g., SINGLE) 

• Acumatica Rate Limit

   

  NOTE: The Acumatica Rate Limit field is based on the order volume. You should verify with the development or implementation team to confirm whether this needs to be completed or modified.

   

• Load Stock Items: If checked, this will load lines UPC from Acumatica StockItem entities.

• Load item dimensions: If enabled, techSHIP loads height, length, width, and weight from Acumatica StockItems.

• Acumatica Order Type: If specified, techSHIP imports only the configured order types.

• Acumatica Warehouse ID: Used to filter shipments when importing by sales orders.

• Flex Field Mapping: Allows binding custom fields in addition to the standard plugin bindings.
  
  

II. ACUMATICA ENDPOINT REQUIREMENTS

WARNING: Configuring the plugin parameters alone is not sufficient. A properly configured Acumatica REST endpoint is required for the integration to function as expected.

i. Default vs. Custom Endpoints

Acumatica provides default REST endpoints (e.g. Default/23.200.001) exposing standard entities.

For techSHIP integrations, we recommend using a dedicated custom endpoint created by cloning a default endpoint and:

• Including only the entities required by techSHIP

• Exposing required child collections and actions

• Exposing any custom fields needed for the project

The Acumatica customer (or their implementation partner) is responsible for creating, configuring, and validating the custom REST endpoint, including:

• Cloning a default endpoint
• Exposing all required entities, child collections, and actions
• Ensuring required fields are editable
• Providing endpoint details and credentials to techSHIP

Failure to complete these steps will block onboarding and delay go-live. 

ii. Required Endpoint Entities & Capabilities

The custom endpoint (e.g. TechshipExt/23.200.001) must expose at minimum:

• Entities

  • SalesOrder

  • Shipment

  • StockItem

  • ShippingBox
    
    

• Child collections
  Child collections must be exposed via $expand to allow techSHIP to retrieve all required shipment and order data in a single request. This avoids partial data retrieval and prevents downstream processing errors.
  Typical child collections include:

  • Order and shipment lines

  • Allocations

  • Packages and package contents

  • Shipping settings and ship-to information
    
    

• Confirm Shipment actions

ConfirmShipment must be enabled on the Shipment entity in the custom Acumatica endpoint to allow techSHIP to confirm shipments in Acumatica after labels and tracking numbers have been generated, and is required to:

• Confirm the shipment in Acumatica
• Update shipment status
• Persist tracking numbers and shipment-related data returned by techSHIP.
  

• Shipment updates
  

The shipment entity must be updatable (PUT enabled) in the custom Acumatica endpoint.

techSHIP uses this capability to push shipment-related updates back into Acumatica before or during shipment confirmation, including:

• Tracking numbers
• Carrier and service selection
• Package details (box, weight, dimensions)
• Freight charges and integration-specific fields

All fields updated by techSHIP must be:

• Exposed in the endpoint
• Marked as editable
• Compatible with any custom validation or workflow logic

NOTE: This onboarding document intentionally focuses on setup requirements and prerequisites. Detailed API behavior and implementation specifics are handled during implementation and are outside the scope of this onboarding requirements document.

III. OTHER CONSIDERATIONS

i. UPC Retrieval Logic (Optional)

When Load Stock Items is enabled, techSHIP retrieves UPC values from the StockItem CrossReferences collection.

1. Cross reference where Description = "UPC"
2. Description = "GTIN/EAN/UPC/ISBN"
3. AlternateType = "UPC"
4. AlternateType = "GTIN/EAN/UPC/ISBN"

If multiple entries match, the first valid match is used.

ii. ShipVia Usage & Critical Mappings

The ShipVia field in Acumatica is a critical control point for shipments imported into techSHIP.

Depending on configuration, ShipVia can be used to:

• Select a Billing Account, or

• Select a Carrier and Service

Only one method is applied per shipment.

1. ShipVia Billing Account: If a BillingAccount or BillingAccountClient in techSHIP has a value matching the Acumatica ShipVia, that billing account is automatically selected during import. 

2. ShipVia Carrier & Service: If a Service Code Mapping exists where External Code = ShipVia,techSHIP selects the mapped carrier and service. In this case, the default billing account is used.

   For more information about this, please see: Best Practices for Carrier and Service Code Mappings setup [Information]

iii. Packing Logic (Critical)

Packing behavior depends on where packaging is performed:

• Packing in techSHIP
  Imported shipments must not contain packages in Acumatica.

• Packing in Acumatica
  Shipments may include packages and contents, which are transferred to techSHIP.