Market catalog --- CSV upload / download

Use this dashboard workflow when you want to edit many catalog rows in one go:

1. Export the current catalog as CSV
2. Edit rows offline
3. Upload CSV back
4. Review detected changes
5. Apply changes

This page covers the owner dashboard flow (Bearer auth). For external read-only API usage with X-API-Key, see market-catalog-external-api{.interpreted-text role="doc"}.

Overview

The MARKET integration has a dedicated tab:

• Upload / Download in integration details
• Export CSV downloads a round-trip CSV with stable headers
• Import CSV analyzes file content first (preview), then applies create/update changes

Current scope:

• Products and variants only
• Missing rows are ignored (not archived)
• Price lists are not part of this CSV flow yet

CSV contract

CSV headers are fixed and ordered:

row_type,product_id,variant_id,status,type_keys,tag_slugs,product_name,product_attributes_json,product_locales_json,variant_sort_order,variant_sku,variant_attributes_json,variant_locales_json

Important rules:

• row_type: product or variant
• product_id:
• optional for new product rows
• required for variant rows
• variant_id:
• optional for new variant rows
• required to update an existing variant row
• type_keys uses | as separator (for product rows)
• tag_slugs uses | as separator (for product rows)
• *_attributes_json and *_locales_json columns must contain valid JSON object values when filled

Preview and apply

The dashboard always runs preview first:

• validates row structure and domain constraints
• resolves row action: created, updated, unchanged, or invalid
• highlights changed fields in the preview table
• shows summary counters

Default preview filter is only changed rows. You can switch to show all rows.

Apply stage:

• requires a preview token from the latest preview response
• fails with conflict if data changed and token is outdated
• applies only create/update operations

Missing rows behavior

Rows that exist in catalog but are absent in uploaded CSV are counted as missing in file and ignored:

• no automatic ARCHIVED status changes
• no deletion

Best practices

• Start from a fresh export before editing
• Keep IDs when updating existing rows
• Avoid changing column order or names
• Use UTF-8 CSV files
• Keep one source of truth for SKU values (variant rows)

Further reading

• External read API and API key scopes: market-catalog-external-api{.interpreted-text role="doc"}
• API keys and permissions: ../../../api/authentication{.interpreted-text role="doc"}