How Catalog Data Flows

Overview

Import and export control how product data is added to and retrieved from the Product Catalog. This feature allows you to upload product data, monitor processing jobs, and export catalog data for external use.

During import, the information in your file, such as product names, prices, or categories, can be matched to the corresponding fields in the Product Catalog. This helps ensure that product data is handled consistently, checked before processing, and is easy to track.

Core Capabilities and Behavior

• Background job processing: Imports and exports run in the background, allowing large product files to be processed without interrupting work in the user interface.

• Clear job tracking: Every import and export is saved with its status, execution time, and result, so you can check progress, review outcomes, or run the same job again if needed.

• Checks before processing: Files and configurations are reviewed before a job starts to identify missing required attributes, file structure issues, or incompatible data types.

• Required attribute validation: Jobs can only be started when all mandatory Product Catalog attributes are correctly mapped.

• Consistent file format: All imports and exports use UTF-8 encoded CSV files to ensure reliable and predictable data handling.

Job Types

When you create a new job in the Import/Export view, you choose a Job type that determines the direction and source of the data transfer.

Each job has a name (up to 100 characters), an optional description (up to 500 characters), a Job type, and a target Product Catalog.

Import Behavior

Imports use a local CSV file that is uploaded to a selected Product Catalog. Each import job can add new variants and update existing variants within the same catalog.

CSV imports always run in update mode. Variants identified by a new variant_id are created; variants whose variant_id already exists in the catalog are updated with the values supplied in the file. Attributes that are not present in the file remain unchanged on existing variants. The mechanics of this behavior are described in Partial Update below.

Import File Requirements

• File format: .csv

• Encoding: UTF-8

• Delimiter: Comma-separated values only

• Maximum file size: 50 MB

• Header row: Required, at least one header must be included

When a file is uploaded, the system checks the file structure by looking for:

• Missing, duplicate, or empty header names

• Rows where the number of columns does not match the header

To support preview and validation, the first 10 rows of the file are read and analyzed.

Attribute Mapping

Each column in the file must be linked to an existing Product Catalog attribute.

• Custom file headers are supported and can be mapped to existing attributes

• Mapping can be done manually or with an Auto-fill option that suggests matches based on the uploaded file

• Each file column can be mapped to one Product Catalog attribute. Multiple columns cannot be mapped to the same attribute, and one column cannot be split across multiple attributes.

• All mandatory attributes must be mapped, even when the variant already exists in the catalog and the mandatory values would not change

• The system checks that the data in the file matches the Data format of the selected attribute, for example, numbers, text, lists, or boolean values

Before the job starts, a summary view allows you to review and adjust the configuration.

Partial Update

An import can update an existing variant with only a subset of its attributes. Attributes that are not included in the file remain unchanged on the variant. This is known as a Partial Update.

Partial Update applies to both CSV imports and API ingestion, and is intended for keeping individual fields, such as price or stock indicator, up to date without resubmitting the full product record.

When to use it:

• Updating selected attributes on existing variants while leaving all other attribute values intact

• Refreshing fast-changing values, such as prices or availability, without sending the complete product record

When not to use it:

• Creating a new variant: all mandatory attributes must be present in the import

• Replacing the full state of a variant: a Partial Update never clears attributes that are absent from the file

Note: Even for Partial Updates, the file must include all mandatory attributes in the mapping (for example, Product ID, Variant ID, Currency, and Variant Status). The Partial Update logic applies to which fields the system overwrites — not to which columns the file must contain. For details, see Attribute Mapping above.

Variant Status on Import

When a new variant is created during an import and the Variant Status column is missing or empty in the file, the system sets Variant Status to ACTIVE (numeric value 1) by default.

For existing variants, Variant Status follows the Partial Update behavior: if the column is omitted from the import, the existing Variant Status remains unchanged. To transition a variant to PREORDER (0) or DISCONTINUED (2), include the Variant Status column with the target value.

For the full description of Variant Status values and their downstream effects, see Product Attribute Model.

Error Handling

During import, validation errors are reported at two levels. The level determines how much of the variant is applied.

Note: When a job completes with attribute errors, the import status is Completed with warnings. The error report lists the affected variant, the attribute that was skipped, and the reason. When all variants fail, the job status is Failed.

Import Jobs

Import jobs run in the background and can have the following statuses:

• Pending

• Processing

• Completed

• Completed with warnings

• Failed

Email notifications inform you whether a job succeeded or failed and, when applicable, include a download link to error files.

Need help preparing your product data?

If your product data needs to be transformed before it fits the Product Catalog structure — for example, splitting combined fields, reformatting localized values, or mapping legacy schemas — the Mapp support team can assist with the preparation. Reach out to your account contact or open a support request for guidance on bringing your data into the required format.

Data Ingestion via Public API

In addition to CSV imports, product data can be ingested using publicly available REST API endpoints. This method supports programmatic synchronization of product data, including incremental Partial Updates of selected attributes on existing variants.

Authentication

API access is authenticated through Mapp Cloud using a Client ID and Client Secret. The same credentials provide unified access across the Mapp Cloud APIs, including Connect, Mapp Intelligence (Analytics), Mapp Engage, and Mapp Fashion. You do not need separate credentials for each service.

Client IDs are created and managed under Settings > Mapp Cloud > API Client IDs. Only users with administrator rights can create Client IDs. Each Client ID is bound to the user who created it.

To authenticate, your application requests a token using the Client ID and Client Secret. The token is then included in subsequent API calls. Tokens have a configurable validity time (default 60 minutes) and remain valid until they expire or are revoked.

The Product Catalog API does not require a separate activation step — any account with access to the Product Catalog can use the API through Client IDs created by an administrator.

API Reference

Endpoint documentation, request and response schemas, and rate limits are published separately. For details, see the Product Catalog Public API reference.

Export Behavior

Exports create a CSV file based on selected Product Catalogs and chosen attributes. You decide which attributes and enrichments are included in each export job.

Export Output and Access

• Exported files are CSV files encoded in UTF-8

• File headers are predefined and cannot be changed

• Optional flattening: enable the flattening option to expand JSON-structured values into separate, first-level columns in the CSV. Without flattening, structured values are exported as JSON in a single column.

• A download link is provided in an email notification sent to the user who started the export job

Export Scope and Content

• Exports reflect the current state of the selected Product Catalog

• Only the attributes selected for the export are included. The selection includes both Active and Inactive attributes, which means an export can contain more columns than are currently available for import.

• Enriched data from Mapp Fashion is included when available

• If a Product Catalog does not contain enriched attributes, the enrichment option is disabled

Language Handling

• Exports support one language per job

• All exported content is currently provided in British English

Limitations (Beta)

The following limitations apply to the current beta release of the Import and Export feature. These restrictions are temporary and are planned to be addressed in future iterations.

• Remote file locations: Importing from or exporting to remote locations such as SFTP or S3 is not supported in the current beta. Support for remote locations is planned for a future release.

• Data transformations: No data transformations are available during import or export in the current beta. Transformation support is planned for later iterations.

• Export language selection: Only one language can be exported per job, and exported content is currently provided in British English. More flexible language configuration is planned for future releases.

• Export header customization: Exported file headers cannot be changed in the current beta.