Version: Next (unreleased)

Field Mapping

Field mapping lets your system talk to the platform in your own schema. Inbound payloads are translated into the internal format; outbound responses and error messages are translated back. Your code never has to know the platform's field names.

Mappings are configured per partner in the dashboard. You can start from a partner template or build one from scratch — see Configuring mappings.

This page describes what the mapping engine can do, so you can design a mapping that fits your payload.

Behavior at a glance

Your request (your field names)
        │
        ▼
Mapping engine  ──►  Internal format  ──►  Validation & persistence
                                                    │
Response (your field names) ◄────────── Reverse mapping

Validation errors use your field names too. If order_number is required but you mapped it from po_number, the error refers to po_number.

Mapping types

The engine supports four transformations. They compose — a single mapping can use all of them.

1. Simple rename

Map one top-level field to another.

In (you send)	Out (internal)
`po_number`	`order_number`
`vendor_name`	`customer_name`

{"po_number": "PO-5001", "vendor_name": "Acme Corp"}

becomes

{"order_number": "PO-5001", "customer_name": "Acme Corp"}

2. Dot-notation (nested read / nested write)

Read from nested objects and/or write into nested objects. Either side can be a path.

In path	Out path
`header.po_number`	`order_number`
`header.vendor.name`	`customer_name`
`header.vendor`	`customer_info`

3. Array index

Pull a value from a specific array position. Useful when header-level data is repeated on every line item.

In path	Out path
`lines[0].order_ref`	`order_number`
`lines[0].ship_to`	`notes`

4. Array-to-array (nested mappings)

Transform an array of objects into another array with renamed keys — for order lines, inventory rows, and so on.

Source Details[]:

[
  {"InventoryID": "RUG-5X7", "OrderQty": 10, "LineNote": "Fragile"},
  {"InventoryID": "RUG-8X10", "OrderQty": 5}
]

Mapped to items[] with InventoryID → sku_code, OrderQty → quantity, LineNote → notes:

[
  {"sku_code": "RUG-5X7", "quantity": 10, "notes": "Fragile"},
  {"sku_code": "RUG-8X10", "quantity": 5}
]

The source path itself can be nested (purchase_order.lines), and inner field_map supports dot-notation too (product.item_code → sku_code).

Static values

Fields that are injected into every request after mapping. Useful for tagging, routing, or fixed metadata.

metadata.source       = "acumatica"
metadata.integration  = true

Every mapped payload will contain:

{"metadata": {"source": "acumatica", "integration": true}}

End-to-end example

Payload your ERP sends:

{
  "OrderNbr": "SO-005123",
  "Customer": {
    "CustomerID": "CUST-100",
    "CustomerName": "ABC Trading"
  },
  "ScheduledShipDate": "2026-05-01",
  "Details": [
    {"InventoryID": "RUG-5X7-BLU", "OrderQty": 10},
    {"InventoryID": "RUG-8X10-RED", "OrderQty": 5}
  ]
}

Mapping (configured once, in the dashboard):

Kind	Source	Target
Rename	`OrderNbr`	`order_number`
Nested read	`Customer.CustomerName`	`customer_name`
Capture subtree	`Customer`	`customer_info`
Rename	`ScheduledShipDate`	`due_date`
Array mapping	`Details[] → items[]`	`InventoryID→sku_code`, `OrderQty→quantity`
Static	—	`metadata.source = "acumatica"`

Resulting internal payload:

{
  "order_number": "SO-005123",
  "customer_name": "ABC Trading",
  "customer_info": {"CustomerID": "CUST-100", "CustomerName": "ABC Trading"},
  "due_date": "2026-05-01",
  "items": [
    {"sku_code": "RUG-5X7-BLU", "quantity": 10},
    {"sku_code": "RUG-8X10-RED", "quantity": 5}
  ],
  "metadata": {"source": "acumatica"}
}

Path syntax reference

Syntax	Meaning	Example
`field`	Top-level key	`po_number`
`a.b`	Nested object	`header.po_number`
`a.b.c.d`	Deep nesting	`purchase.header.vendor.name`
`a[0].b`	Array element	`lines[0].order_ref`
`a.b` (target)	Creates nested out	`metadata.source`

When no mapping is configured

If a partner has no active mapping for a resource, payloads pass through as-is and must use internal field names. Fine for quick tests; partner templates are the recommended path for production.

Behavior at a glance​

Mapping types​

1. Simple rename​

2. Dot-notation (nested read / nested write)​

3. Array index​

4. Array-to-array (nested mappings)​

Static values​

End-to-end example​

Path syntax reference​

When no mapping is configured​

See also​