> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/tutorials/omnitron/sales-channels/content-management/how-to-configure-merchant-feed-adapter.md). # How to Configure Merchant Feed Adapter? This document provides a comprehensive guide for configuring and managing **Merchant Feed Adapters** within the **Omnitron**, an essential tool for exporting structured product data to external platforms. Merchant feeds are used to display products on comparison shopping engines, search engines, or affiliate platforms—allowing users to view product details, prices, and availability without visiting the brand’s actual e-commerce site. To support this, Omnitron enables merchants to generate and customize **XML feed files** based on their own schema requirements, language preferences, pricing lists, and filtering logic. Whether you are creating a feed for a single market or managing a complex multi-language, multi-region catalog, this tutorial walks you through: * Setting up new feed adapters through the Omnitron * Structuring feed content using `schema_data` * Mapping product attributes with flexible rule-based logic * Filtering the feed by SKU or base code using uploaded files * Managing multiple feeds by language and pricing combinations * Manually or automatically triggering feed generation * Accessing the final XML output via a generated file URL By the end of this guide, you will be able to confidently configure and launch feeds that are optimized for your sales channels, meet third-party specifications, and scale across multiple locales with ease. ## Add Merchant Feed Adapter in Omnitron To begin creating a Google Merchant Feed Adapter, follow the steps below. ### Navigate to the Feed Adapter Section {% stepper %} {% step %} Go to **Sales Channels > Content Management > Google Merchant Feed Adapter.** {% endstep %} {% step %} From this page, you can **view existing adapters**, **edit them**, or **add new ones**. {% endstep %} {% step %} Click on **“+ New Google Merchant Feed Adapter”** to open the adapter creation form.
{% endstep %} {% endstepper %} ### Fill in Basic Adapter Settings {% stepper %} {% step %} At the top of the page, you’ll see a set of core fields to define the adapter:
FieldDescription
NameA unique name for the feed adapter. This is used to distinguish between different feeds, especially in multi-language or multi-region setups.
Example: insider, google_feed_en, feed_ar_uae
Adapter TypeDefines which adapter class will handle feed generation. Select base unless your project includes a custom implementation.
StatusSet this to Active to allow the adapter to be used during scheduled or manual feed generation. If set to Passive, it will be ignored by automatic processes.
One timeCheck this box if you want the feed to only be triggered manually. This disables scheduled executions.
File URLThis field is automatically filled after feed generation. It provides a direct link for the generated XML file.
Choose File(Optional) Upload a filter file in .csv or .xls format. The system will convert it to base64. The file should contain sku or base_code headers to restrict which products are included in the feed.
{% endstep %} {% step %} If you're generating feeds for multiple markets, it's a best practice to name the adapter accordingly (e.g., `google_feed_ar_ksa`) and define separate adapters per language/price list. {% endstep %} {% endstepper %} ### Configure Feed Schema (`config` field) Once the basic adapter settings are filled, the next critical step is configuring how the feed will be generated. This is done through the **`config` field**, which is a JSON object that defines the structure, behavior, and formatting rules for the XML file that will be generated. This configuration directly determines: * Which product attributes are included * What the output file is named * How images, categories, and language-specific values are handled * Whether out-of-stock products are shown * How visual content (like cropped images or additional images) is formatted #### Example Configuration: ```json { "chunk_size": 100, "schema_data": [ { "tag": "description", "attr_type": null }, { "tag": "g:gender", "attr_type": null, "default_value": "Default" }, { "tag": "title", "attr_type": null, "default_value": "title" } ], "EXTRA_IMAGES": true, "feed_filename": "insider/insider-feed_en.xml", "IS_ALL_SMALL_IMAGE": true, "url_attribute_data": null, "THUMBNAIL_CROP_TYPE": "Center", "extra_image_configs": [ { "tag_name": "g:image_link", "tag_option": { "crop": "Center", "width": 1080, "height": 1080 } } ], "IS_REQUIRED_SMALL_IMAGE": true, "category_attribute_data": [ "category_name_en-us" ], "include_stock_out_products": true, "price_list_id": 1, "stock_list_id": 3, "category_name_translate_key": "category_name_en-us", "MERCHANT_FEED_VISILABS_IMAGE_TAG": "g:additional_image_link", "MERCHANT_FEED_VISILABS_IMAGE_SIZE": { "crop": "Center", "width": 1080, "height": 1080 }, "CUSTOM_CATEGORY_MAPPING_ENABLED": true, "category_ids_dict": { "00010001": "custom category id" }, "category_dict": { "00010001": "custom category name" } } ``` #### Explanation of Key Fields:
FieldDescription
chunk_sizeNumber of products processed per task run. Useful for optimizing large feeds. Must be greater than 0 and less than 1000.
Setting a value outside this range may result in validation errors or failed feed generation.
schema_dataList of tags to be included in the feed. Each item defines one XML tag. Optionally include a default_value if the mapped attribute is missing.
EXTRA_IMAGESEnables inclusion of first product image in the feed.
feed_filenamePath + filename for the output feed. This should be unique per language/market.
IS_ALL_SMALL_IMAGEEnsures small image versions are used where applicable.
url_attribute_dataUsually null unless custom logic is used for URL mapping.
THUMBNAIL_CROP_TYPECropping strategy for image thumbnails. Options may include Center, Top, Bottom, etc.
extra_image_configsDefines how extra images (e.g., g:image_link) should be rendered, including size and crop strategy.
IS_REQUIRED_SMALL_IMAGEForces the presence of small-sized images in the feed.
category_attribute_dataList of category-related product attributes. These are used when building the product's category tree or name.
include_stock_out_productsIf true, includes products that are out of stock.
price_list_id / stock_list_idUsed to pull price and stock info from specific price/stock lists configured in Omnitron. Useful for multi-market feeds.
category_name_translate_keyAttribute key used to get the translated category name (e.g., for localized feeds).
MERCHANT_FEED_VISILABS_IMAGE_TAGSpecifies the tag under which additional images for Visilabs integration are exported.
MERCHANT_FEED_VISILABS_IMAGE_SIZEImage dimensions and crop settings used for Visilabs-specific image feeds.
CUSTOM_CATEGORY_MAPPING_ENABLEDEnables manual category mapping by path. If set to true, feed category values can be overridden using category_ids_dict and category_dict.
category_ids_dictDictionary to override <category_code> based on category path value.
Format: "{path}": "custom_code_value"
See: Getting category path information
category_dictDictionary to override <category_name> based on category path value.
Format: "{path}": "custom_name_value"
duplicate_fieldsCopies the value of an existing tag into a new tag under a different name. Accepts a list of {"source": ..., "target": ...} objects. The duplication runs after all other tags are generated, so the target always mirrors the final value of the source.
Example: [{"source": "g:sale_price", "target": "sale_price"}]
### Price and Discount Configuration By default, the feed derives its price tags from the product's price and retail (list) price: * `g:price` → the **retail/list price** (the "struck-through" price) when the product has a discount. * `g:sale_price` → the **actual selling price**. When the product has no discount (no retail price, or price ≥ retail price), only `g:price` is written. You can fine-tune this behavior with the flags below—all of them are optional and belong in the same `config` JSON object.
FieldDescription
CONCAT_PRICE_CURRENCYBoolean, default true. Appends the currency code to every price value (e.g. 995.00 TRY). Set to false to output the numeric value only (e.g. 995.00).
ALWAYS_INCLUDE_SALE_PRICEBoolean, default false. When a product has no discount, still emits an empty <g:sale_price> tag instead of omitting it. Useful for platforms that require the tag to always be present.
SALE_PRICE_WITH_BASKET_OFFERSBoolean, default false. Overwrites g:sale_price with the discounted price of the product's single-unit (quantity = 1) basket offer, so the sale price reflects the basket promotion. Requires the OFFER_SHOW_LISTING_KWARGS dynamic setting to be enabled (see hint below). Note: this replaces the real sale price—use INCLUDE_BASKET_OFFER_PRICE instead if you need to keep both.
INCLUDE_BASKET_OFFER_PRICEBoolean, default false. Emits an additional <g:basket_price> tag containing the discounted price of the product's single-unit (quantity = 1) basket offer, without touching g:price or g:sale_price. The tag is only written when the product actually has a matching offer. Requires the OFFER_SHOW_LISTING_KWARGS dynamic setting to be enabled.
add_sale_price_as_priceBoolean, default false. If a sale price exists, moves it into g:price and drops g:sale_price, so the feed exposes a single (discounted) price.
#### Showing three separate prices (list, sale, and basket-offer price) A common requirement is to expose the struck-through price, the sale price, **and** a separate basket-offer price at the same time. Enable `INCLUDE_BASKET_OFFER_PRICE` and leave `SALE_PRICE_WITH_BASKET_OFFERS` off: ```json { "INCLUDE_BASKET_OFFER_PRICE": true } ``` For a product with a list price of 2095.00, a sale price of 995.00, and a single-unit basket offer of 696.50, the feed then outputs: ```xml 2095.00 TRY 995.00 TRY 696.50 TRY ``` {% hint style="info" %} `SALE_PRICE_WITH_BASKET_OFFERS` and `INCLUDE_BASKET_OFFER_PRICE` are independent. Enabling `SALE_PRICE_WITH_BASKET_OFFERS` overwrites `g:sale_price` with the offer price (losing the real sale price), whereas `INCLUDE_BASKET_OFFER_PRICE` keeps `g:sale_price` intact and adds the offer price as a separate `g:basket_price` tag. There is no need to also duplicate the sale price via `duplicate_fields` when you use `INCLUDE_BASKET_OFFER_PRICE`. {% endhint %} {% hint style="warning" %} Both basket-offer flags rely on the offer's listing data (`discounted_total_price`), which is only exposed when the **`OFFER_SHOW_LISTING_KWARGS`** dynamic setting is enabled for the project. If that setting is off, the basket-offer price will not appear even when the flag is set. {% endhint %} ### Upload Filter Files (Optional) To include only specific products in the feed, you can upload a filter file—**CSV** or **XLS**—containing product identifiers. Filter files help reduce feed size or tailor feeds to campaign-specific product lists. For example, if you want to export only a selection of SKUs for a seasonal collection, use a filter. {% stepper %} {% step %} Go to the **Choose File** field in the adapter form. {% endstep %} {% step %} Upload a `.csv` or `.xls` file. {% endstep %} {% step %} File must contain a `sku` or `base_code` column. {% hint style="warning" %} If the file format or header is incorrect, the system will return an error:\ `No valid header found in file headers.` {% endhint %} {% endstep %} {% step %} You can also combine the uploaded filter file with additional config-based filters via the `filter_arguments` key in the config: ```json "filter_arguments": { "is_listable": true } ``` This way, only listable products **that also match the uploaded SKUs** are included in the feed. {% endstep %} {% endstepper %} ### Save and Generate the Feed Once you’ve completed the **Basic Adapter Settings**, added your **config JSON**, and optionally uploaded a **filter file**, it’s time to save the adapter: * Click **“Save”.** * If your `config` field is valid and includes a `schema_data` section, the page will reload and reveal a new section called **Mapper Settings**. * This section allows you to define the transformation logic for each XML tag listed in your `schema_data`. {% hint style="warning" %} If you skip the config or forget to include `schema_data`, the Mapper Settings section will **not** be displayed. {% endhint %} ## Attribute Mapping with Rules and Actions After configuring your feed schema using the `config` field, the next crucial step is to **define how each XML field (tag) retrieves its data** from the product catalog. This is done using the **Mapper Settings** section in the adapter interface. Each XML tag listed under `schema_data` must have a corresponding **mapper**, which includes: * A **rule** that determines when the mapping should be applied * An **action** that defines how to fetch or transform the data Together, these enable complex conditional logic, localization, and formatting for your feeds—ensuring data consistency and compatibility with platforms like Google Merchant Center.
Each mapper is a JSON object with two main parts: #### 1. `rule`: *When should this mapping be applied?* Defines the condition that must be true for the action to run. #### 2. `action`: *How should the value be retrieved or constructed?* Specifies how to fetch, format, or combine values. ### Rule Types (When)
Rule TypeDescription
alwaysAlways applies the action, regardless of product data
attributeexistsApplies only if a specific attribute exists on the product
multiattributeexistsChecks if multiple attributes exist (can be all or any)
queryApplies if a certain query condition is met (advanced)
in_dictChecks if a field exists in a predefined dictionary
### Action Types (How)
Action TypeDescription
attrgetterRetrieves a single attribute value
attrformatterFormats an attribute using a custom template
multiattrformatterCombines multiple attributes into a single string
outputdictUses a dictionary to map internal values to output values
stdoutOutputs a static value (useful for fixed tags)
#### Basic Example: Simple Attribute Getter This mapper fetches the `description` field from the product data and maps it directly to the `` XML tag. ```json { "rule": { "rule_type": "always" }, "action": { "action_type": "attrgetter", "action_kwargs": { "input_key": "description" } } } ``` #### Example: Formatting Gender Using Output Dictionary If your internal values for gender are stored as `M`, `F`, and `U`, but Google requires `male`, `female`, and `unisex`, use this: ```json { "rule": { "rule_type": "always" }, "action": { "action_type": "outputdict", "action_kwargs": { "input_key": "gender", "mapping_dict": { "M": "male", "F": "female", "U": "unisex" } } } } ``` #### Combine Multiple Attributes Use this action when you need to generate a value from multiple fields (e.g., combining brand + title + size). ```json { "rule": { "rule_type": "always" }, "action": { "action_type": "multiattrformatter", "action_kwargs": { "input_keys": ["brand", "title", "size"], "format_str": "{0} - {1} ({2})", "delimiter": " " } } } ``` **Output Example:** `Nike - Air Max (42)` ### Handling Localized Fields When generating feeds in **multiple languages**, you need to retrieve the correct **language-specific values** from product data. The format of your `input_key` inside the **mapper's `action_kwargs`** will vary depending on: * Whether the feed is for the **default language** * Whether the field is a **text** or **dropdown** attribute #### For Default Language Feeds If you're generating a feed in your **default language**, product attribute values can be accessed using this structure: ```json "input_key": "attributes__{{attr_code}}" ``` This directly pulls the attribute from the product's default data. #### For Localized Feeds (Non-Default Languages) For other languages (e.g., Arabic, Turkish, English (US)), you need to reference **localized fields**. The structure depends on the **type of attribute**. #### For text fields: Use `localized_attributes` for retrieving translated text fields such as `title`, `description`, or `long_name`. ***Pattern:*** ``` localized_attributes__{{language_code}}__{{attribute_code}} ``` ***Example:*** ```json [ { "rule": { "rule_type": "always", "rule_kwargs": {} }, "action": { "action_type": "attrgetter", "action_kwargs": { "input_key": "localized_attributes__en-us__l_name" } }, "shared_kwargs": {} } ] ``` #### For dropdown fields: For dropdown attributes that have translated options (e.g., brand, material, gender), use the `attributes_kwargs` structure to access the translated label. ***Pattern:*** ``` attributes_kwargs__{{attribute_code}}___translations__{{language_code}}__label ``` ***Example:*** ```json [ { "rule": { "rule_type": "always", "rule_kwargs": {} }, "action": { "action_type": "attrgetter", "action_kwargs": { "input_key": "attributes_kwargs__brand___translations__ar__label" } }, "shared_kwargs": {} } ] ``` {% hint style="warning" %} Use the appropriate `language_code` (e.g., `en`, `ar`, `tr`) depending on the feed’s target market. {% endhint %} ## Triggering and Monitoring Feed Generation Once your Merchant Feed Adapter is configured and saved, it's time to **generate the actual XML feed file**. Omnitron provides both **automated** and **manual** triggering methods for this purpose. You can also **track the status** of the generation process and retrieve the final file URL programmatically. **Automatic vs. Manual Triggering:**
Trigger TypeDescription
Automatic (Scheduled)If the adapter's One Time checkbox is unchecked, Omnitron will automatically run the feed generation task every 3 hours.
Manual (One-Time)If One Time is checked, the feed must be triggered manually via the API or Omnitron UI. This is useful for test feeds, campaign-based feeds, or ad-hoc exports.
### Trigger Feed Generation Manually (API) To manually trigger feed generation for a specific adapter: #### **Endpoint:** ```bash POST /api/v1/remote/1/google_merchant_feed_adapter/{adapter_pk}/trigger_task/ ``` Replace `{adapter_pk}` with the ID of the adapter you want to trigger. #### Example Request: ```bash curl --location --request POST 'https://your-commerce-url/api/v1/remote/1/google_merchant_feed_adapter/268/trigger_task/' \ --header 'Authorization: Token your_token_here' ``` #### Example Response ```json { "cache_key": "6c27bc5a8f06442f96044302e6168d7a" } ``` ### Monitor Progress of Feed Generation You can track the progress of the feed task using the returned `cache_key`. #### Endpoint: ```bash GET /api/v1/remote/1/google_merchant_feed_adapter/{adapter_pk}/trigger_status/?cache_key={cache_key} ``` #### Example Request: ```bash curl --location 'https://your-commerce-url/api/v1/remote/1/google_merchant_feed_adapter/268/trigger_status/?cache_key=6c27bc5a8f06442f96044302e6168d7a' \ --header 'Authorization: Token your_token_here' ``` #### Example Response: ```json { "completed_tasks": 1, "data": [ { "progress": [1, 1], "completed": true, "chunk_count": 1 } ], "progress_count": 1 } ``` {% hint style="warning" %} **`progress: [x, y]`** represents **x completed chunks out of y total**. You can calculate progress percentage as:\ `(x / y) * 100` {% endhint %} ### Get Feed File URL Once the task is completed, the file will be available at the adapter’s detail endpoint. #### Endpoint: ```bash GET /api/v1/remote/1/google_merchant_feed_adapter/{adapter_pk}/ ``` #### Example Request: ```bash curl --location 'https://your-commerce-url/api/v1/remote/1/google_merchant_feed_adapter/268/' \ --header 'Authorization: Token your_token_here' ``` #### Example Response: ```json { ... "file_url": "https://cdn.akinoncloud.com/google/insider-feed_en.xml" } ``` You can now use this file URL in your Google Merchant Center, comparison shopping platforms, or campaign tracking tools. ### Error Handling If a feed task is already in progress and a new one is triggered: #### Example Response: ```json { "non_field_errors": "Google Merchant Feed task is already running. Please wait until the current task is completed before starting a new one.", "error_code": "google_merchant_feed_adapter_100_2" } ``` {% hint style="warning" %} Always check if a task is running before triggering a new one to avoid queue conflicts. {% endhint %} ### Triggering Feed Manually via Omnitron In addition to using API calls, you can also **manually trigger feed generation directly from the Omnitron interface**—with just a few clicks. {% stepper %} {% step %} **Select the Feed Adapter(s):** Use the checkbox on the left to select the adapter(s) you want to run. You can select one or multiple rows. {% endstep %} {% step %} **Open the "Select Action" Dropdown:** At the top of the list, open the **Select Action** dropdown. {% endstep %} {% step %} **Click “Trigger Task with Selected Items”:** This option will immediately initiate the feed generation task for the selected adapters.
{% endstep %} {% step %} **Click “Apply”:** The task will be queued and executed via Celery. You can monitor the task’s status using the API or check the file URL once generation is complete.
{% endstep %} {% endstepper %} ## Feed URL Usage Once the feed generation is complete, the XML file becomes accessible via the provided `file_url`.\ For example, you can access the generated feed directly at: {% embed url="" %}
You can now use this URL to upload the feed to Google Merchant Center or share it with external platforms that support scheduled product feed imports. {% hint style="warning" %} This URL remains valid as long as the feed is not deleted or regenerated under a different filename. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.akinon.com/tutorials/omnitron/sales-channels/content-management/how-to-configure-merchant-feed-adapter.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.