Documentation

Export schema and transformations

Create a JSON export profile

POST /api/v1/exports

{
  "site_id": 1,
  "name": "Catalog for the store",
  "format": "json",
  "output_module": "json",
  "schema": [
    {"source":"sku","target":"id","cast":"string"},
    {"source":"name","target":"title"},
    {"source":"price","target":"offer.price","cast":"decimal","when_empty":"null"}
  ],
  "format_options": {"pretty":true}
}

Each source must exist in the site's field schema or the system-field dictionary; retrieve these through the export details. A successful response returns 201 and a profile, not a prepared file. code is optional and generated when omitted. format may be csv, json, or xml. If you omit schema, the platform proposes an initial mapping.

Field rule

Key	Purpose
`source`	Where to read the value
`target`	Output name; dots create nesting and `images[]` creates an array
`label`	Human-readable CSV column heading
`cast`	Type conversion; allowed values are returned by export details
`when_empty`	Empty-value behavior; use the profile dictionary
`default`	Replacement value when the corresponding mode is selected
`split`	Separator for a string list, up to 8 characters

For example, offer.price creates a nested JSON object. CSV has no nesting: it becomes a corresponding column. XML element names must be valid XML names.

Format options and filters

CSV supports one-character delimiter, eol (lf or crlf), and boolean bom. JSON supports pretty and group_by; XML supports root and item. A simple JSON grouping uses an output-field path in group_by. For more complex aggregates, use dataset transformation.

{"filters":{"where":[{"field":"price","op":"gt","value":0}]},"include_deleted":false}

Operators are =, !=, contains, empty, not_empty, gt, and lt. At most 50 conditions are supported. Check fields and values against actual records.

Code transformation

PUT /exports/{id}/transformation

{"mode":"mapping","source":null,"base_version_id":null}

mapping means ordinary field mapping; records changes records while preserving count and order; dataset supports grouping and filtering a set. For code, send source with a run(\Sdk\Context $ctx) function. Set base_version_id to the current converter_version_id from export details, or null for the first edit. This prevents overwriting someone else's changes. On conflict, reload the export and reconcile your edits.

Preview with GET /exports/{id}/preview. Dataset mode accepts at most 10,000 input records and 16 MB. Through an endpoint, it processes only the current page. Code transformations and previews consume processing budget just like actions in the interface.

See code-based export transformation for the complete rules.