Mappings

For merchants

Where: Settings → Extensions → Export mappings

A mapping describes the document the receiving system gets. It is an allow-list: only fields you map are sent — nothing else from the order leaks out.

Editing a mapping

Card	What you do there
General information	Name, description and Target format — JSON or XML.
Mapping definition	The mapping itself, written as JSON. Invalid JSON or an invalid definition is flagged when you save.
Test mapping	Choose a real order and click Test mapping. You see the rendered document and any field errors. Nothing is sent anywhere.
Import / Export	Copy a mapping out as JSON or YAML, or paste one in — handy for moving mappings between staging and production.

Publish turns the current definition into a new, numbered, read-only version (v1, v2…). Targets always use the published version; a mapping that has never been published shows Not published and cannot be exported with. Edit freely, test, then publish again.

Writing a definition

The definition mirrors the document you want. Each field says where its value comes from:

You write	Result
{"path": "order.orderNumber"}	The value at that path in the order. A missing value gives null, not an error.
{"expr": "money(order.amountTotal)"}	The result of an expression — maths, conditions, functions.
"SHOPWARE" or {"literal": "SHOPWARE"}	A fixed value. Numbers and true/false work too.
{ "name": …, "email": … }	A nested object.
{"each": "order.lineItems", "as": "item", "where": "…", "map": {…}}	A list: one entry per line item (or any other list), optionally filtered.

Everything in the order is available under order. — order number, dates, amounts, currency, customer, billing and shipping addresses with country, line items, deliveries with shipping method, transactions with payment method, tags, sales channel, state and more. Use Test mapping to see what an order contains.

A complete example

{
  "orderNumber": { "path": "order.orderNumber" },
  "orderDate":   { "expr": "format_date(order.orderDateTime, 'Y-m-d')" },
  "source": "SHOPWARE",
  "customer": {
    "name":    { "expr": "concat(order.orderCustomer.firstName, ' ', order.orderCustomer.lastName)" },
    "email":   { "path": "order.orderCustomer.email" },
    "country": { "expr": "country_iso(order.billingAddress.country.iso)" }
  },
  "lines": {
    "each": "order.lineItems",
    "as": "item",
    "where": "item.type == 'product'",
    "map": {
      "sku": { "path": "item.payload.productNumber" },
      "qty": { "path": "item.quantity" },
      "net": { "expr": "money(item.totalPrice)" },
      "vat": { "expr": "tax_rate(item.price.calculatedTaxes[0].taxRate)" }
    }
  },
  "total": { "expr": "money(order.amountTotal)" }
}

Rendered against an order:

{
  "orderNumber": "10001",
  "orderDate": "2026-09-01",
  "source": "SHOPWARE",
  "customer": { "name": "Ada Obi", "email": "ada@example.com", "country": "NG" },
  "lines": [ { "sku": "SW10001", "qty": 2, "net": 100, "vat": 19 } ],
  "total": 119
}

Promotion and shipping lines are left out by the where filter.

Functions

Function	Does	Example
concat(a, b, …)	Joins values as text; empty values are skipped	concat(order.orderCustomer.firstName, ' ', order.orderCustomer.lastName)
default(value, fallback)	fallback when value is empty	default(order.customerComment, '')
money(amount, decimals = 2)	Rounds to a clean number	money(order.amountTotal)
format_date(date, format = 'Y-m-d', timezone = 'UTC')	Formats a date (PHP format)	format_date(order.orderDateTime, 'd.m.Y H:i', 'Africa/Lagos')
country_iso(code)	Upper-cases a country code	country_iso(order.billingAddress.country.iso)
tax_rate(rate)	A tax rate as a number	tax_rate(item.price.calculatedTaxes[0].taxRate)

tax_rate() with a list of taxes returns 0

tax_rate() is meant to also accept the whole list of calculated taxes and return the highest rate, but in 0.9.0-beta.1 that returns 0. Pass a single rate as in the example above. See Known issues.

The full syntax — operators, conditions, lists — is in the mapping language reference.

XML output

With Target format: XML, the same definition is written as XML with the root element <order>. List entries become repeated elements.

Keep payloads stable

The plugin skips an export when the rendered document is identical to the last one that succeeded. Avoid values that change on every render (current time, random IDs) — they make every export look new.