Skip to content
Akmelo

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.