mcp-server

Finish the setup wizard of an ad and ACTIVATE it. Use this when configure_ad_step reports nextStepType 'summary' and the user wants the ad live. In AUTO product mode this publishes EVERY matching product to the LIVE ad channel; for a test set manual mode first (set_ad_manual_mode) — see activationBehavior in get_ad. Returns {integrationId, stepType:'summary', status, nextStepType:null, transitions[], message}; 'validation_failed' when the product filter matches nothing. Export and submission run ASYNC — poll ad_status. Needs confirm:true after the user agrees. ad_id is from list_ads. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Finish the setup wizard of a marketplace and ACTIVATE it. Use this when configure_marketplace_step reports nextStepType 'summary' and the user wants the marketplace live. In AUTO product mode this publishes EVERY matching product to the LIVE marketplace; for a test set manual mode first (set_marketplace_manual_mode) — see activationBehavior in get_marketplace. Returns {integrationId, stepType:'summary', status, nextStepType:null, transitions[], message}; 'validation_failed' when the product filter matches nothing. Export and submission run ASYNC — poll marketplace_status. Needs confirm:true after the user agrees. marketplace_id is from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Turn ON order syncing for a standalone order connection. Use this when the user wants a connection's orders imported; check it with test_order_connection first. Returns {connectionId, action:'configure', status, orderStatus, message}; 'prerequisite_not_met' (HTTP 409, nothing saved) when authentication is unfinished in the Koongo UI, or when activating is not included in this Koongo account or cannot be confirmed now (then try later). Undo with disable_order_connection. connection_id is from get_order_overview; project_id OPTIONAL.

Get the live run status of one ad: readiness, connection, and product counts. Use this to check an ad's run progress and product counts. Ads are product-listing channels (Google Shopping, Meta catalog, Microsoft, price comparison) for the merchant's physical products, not marketplaces: they publish products to the channel and have no order sync. Returns {integrationId, status, ready, lastStep, isReady, isConnected, isOverlimit, productsRefreshing, productsSubmitting, productStats:{listed, processing, errors, inactive, total}}. productStats counts the products in the ad feed. isOverlimit=true means the product count is above what this Koongo account includes; explain that to the user. productsRefreshing=true means an export / feed generation is running (the ad is 'updating'); productsSubmitting=true means items are being pushed to the channel. While EITHER is true the data is still changing — this is the signal to WAIT: after any export (finishing the wizard summary, repair_ad, a step transition that re-exports, or a submit) poll ad_status until BOTH productsRefreshing AND productsSubmitting are false, THEN read the results. The KOONGO DATA CHECK (get_ad_report's dataCheckErrors) and the productStats counts are only current once the refresh has finished — reading mid-refresh gives stale/empty data. ad_id is the id from categoryAttributeWarmup is the OTHER wait: on channels whose attributes depend on the mapped categories, that download runs in the background. While the block is present with pending:true the category-driven attributes are NOT in get_ad_attributes yet — poll ad_status (retryAfterSeconds says how long to wait; state 'rescheduled' means a channel rate limit parked it until nextTryAt) until the block is absent or state is 'ready'. state 'failed' is terminal: call refresh_ad_category_attributes ONCE to start it again, do not poll on. list_ads. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). Use ad_status for run progress and get_ad for configuration/mapping. For the detailed error breakdown use get_ad_report.

AD items: clean — clear the chosen items' listing record in Koongo without a new submit. Use this to reset specific items before submitting them. Needs confirm:true after the user agrees. Target item_ids or all_items:true.

MARKETPLACE items: clean — clear the chosen items' listing record in Koongo without a new submit. Use this to reset specific items before submitting them. Needs confirm:true after the user agrees. Target item_ids or all_items:true.

AD items: clean + resubmit — clear the chosen items' channel listing and submit them again to the LIVE ad channel. Use this when specific listings are stuck or rejected. Needs confirm:true after the user agrees. Target item_ids or all_items:true.

AD-wide clean + resubmit all — clear every item record and submit all again to the LIVE ad channel; pauses the integration meanwhile, and a repeat within 5 minutes starts no new run. Use this when the user asks to rebuild all listings. Needs confirm:true after the user agrees.

MARKETPLACE-wide clean + resubmit all — clear every item record and submit all again to the LIVE marketplace; pauses the integration meanwhile, and a repeat within 5 minutes starts no new run. Use this when the user asks to rebuild all listings. Needs confirm:true after the user agrees.

MARKETPLACE items: clean + resubmit — clear the chosen items' channel listing and submit them again to the LIVE marketplace. Use this when specific listings are stuck or rejected. Needs confirm:true after the user agrees. Target item_ids or all_items:true.

Clone an ad — create a copy of it (settings and configuration) as a new ad. Use this to copy an ad configuration to a new ad. Ads are product-listing channels (Google Shopping, Meta catalog, Microsoft, price comparison) for the merchant's physical products, not marketplaces: they publish products to the channel and have no order sync. Returns {integrationId, action:'clone', status:'cloned', kind:'ads', editUrl, message}, where integrationId is the id of the NEW clone. ad_id is the source ad from list_ads. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Clone a marketplace — create a copy of it (settings and configuration) as a new marketplace. Use this to copy a marketplace configuration to a new marketplace. Returns {integrationId, action:'clone', status:'cloned', kind, editUrl, message}, where integrationId is the id of the NEW clone. marketplace_id is the source marketplace from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Configure ONE step of an ad's setup wizard and save it. Saving a step never activates or publishes: the summary step is refused here — finish setup with activate_ad. Use this to set up an ad step by step IN ORDER, repeatedly targeting each step the previous result reported as nextStepType, until nextStepType is 'summary' (then call activate_ad). Identify the step by step_index (from get_ad steps[].index) — step_type alone targets the FIRST step of that type. Out-of-order calls return 'prerequisite_not_met' / 'step_not_available'. CONNECTION IS NOT CONFIGURABLE HERE: the connection/auth step (credentials, API keys, OAuth) can never be set through MCP. 'oauth_required' / 'credentials_in_ui' is TERMINAL — hand the returned oauthUrl or editUrl to the USER, then STOP and wait; do NOT resend the step, guess field codes or retry. Returns {integrationId, stepType, status, ready, lastStep, nextStepType, oauthUrl, transitions[], message}; status is 'saved', 'oauth_required', 'credentials_in_ui', 'prerequisite_not_met', 'step_not_available' or 'validation_failed'. A product export/generation and a deferred category-attribute download run ASYNC — poll ad_status (productsRefreshing, productsSubmitting, categoryAttributeWarmup) before trusting counts or reading the attribute list. A dropdown field takes options[].value, never its position in the list. Full walkthrough (every step type's payload, the product-filter flags, optionsPending, the deferred-attribute branch): call get_koongo_help with slug 'ad-wizard-steps'. ad_id is from list_ads / create_ad. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Configure ONE step of a marketplace's setup wizard and save it. Saving a step never activates or publishes: the summary step is refused here — finish setup with activate_marketplace. Use this to set up a marketplace step by step IN ORDER, repeatedly targeting each step the previous result reported as nextStepType, until nextStepType is 'summary' (then call activate_marketplace). Identify the step by step_index (from get_marketplace steps[].index) — step_type alone targets the FIRST step of that type. Out-of-order calls return 'prerequisite_not_met' / 'step_not_available'. CONNECTION IS NOT CONFIGURABLE HERE: the connection/auth step (credentials, API keys, OAuth) can never be set through MCP. 'oauth_required' / 'credentials_in_ui' is TERMINAL — hand the returned oauthUrl or editUrl to the USER, then STOP and wait; do NOT resend the step, guess field codes or retry. Returns {integrationId, stepType, status, ready, lastStep, nextStepType, oauthUrl, transitions[], message}; status is 'saved', 'oauth_required', 'credentials_in_ui', 'prerequisite_not_met', 'step_not_available' or 'validation_failed'. A product export/generation and a deferred category-attribute download run ASYNC — poll marketplace_status (productsRefreshing, productsSubmitting, categoryAttributeWarmup) before trusting counts or reading the attribute list. A dropdown field takes options[].value, never its position in the list. Full walkthrough (every step type's payload, the product-filter flags, optionsPending, the deferred-attribute branch, order sync): call get_koongo_help with slug 'marketplace-wizard-steps'. marketplace_id is from list_marketplaces / create_marketplace. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Save a standalone order connection's Orders Config and sync level. Use this to change an order connection's settings. order_config is a {code: value} map using codes from get_order_connection.orderConfigFields; order_sync_level is 'orders_and_stock' or 'stock_only'. Turning syncing on or off is a separate tool: activate_order_connection / disable_order_connection. Returns {connectionId, action:'configure', status, orderStatus, message}: 'updated' on success; 'rejected' (HTTP 400) if you tried to set an unknown, locked or unavailable field (NOTHING is saved — message lists them). Only order settings are changed here — marketplace credentials are never set via MCP. Provided order_config keys are merged (other settings are left untouched). connection_id is from get_order_overview. project_id is OPTIONAL (project_id_required otherwise — then call list_projects). Saved values overwrite the previous ones, which are not returned.

Create a new ad for a project from one of the channels in list_ad_channels. Use this when the user asks to add an ad channel for their products. Ads are product-listing channels (Google Shopping, Meta catalog, Microsoft, price comparison) for the merchant's physical products, not marketplaces: they publish products to the channel and have no order sync. channel_code is the channelCode from list_ad_channels. Returns {integrationId, action:'create', status, kind:'ads', editUrl, nextStepType, message}. status is 'created' (the ad exists; continue with configure_ad_step starting at nextStepType) or 'prerequisite_not_met' (HTTP 409 — message explains what must be done first, e.g. an offer/primary feed must exist first, or another ad is not included in this Koongo account (the message explains it); nextStepType names the step). multichannel_code links a multichannel definition when the channel offers one. definition_code picks a SPECIFIC definition of the channel when it has more than one — take it from get_ad_channel definitions[].definitionCode; omit it for the channel's default/primary definition. name is an OPTIONAL human-readable label so you can later find this ad by name (names are not unique — set_ad_name can change it later). project_id is OPTIONAL (inferred for a single-project customer; if project_id_required is returned, call list_projects and pass project_id). The returned integrationId is the ad_id for get_ad / configure_ad_step and other ads tools.

Create a Koongo product feed for a project. Use this when the user asks for a new product feed. feed_code must be one returned by list_feed_templates. Returns {feedId, feedCode, status, customerId, editUrl, categoryMappingNeeded}. project_id is OPTIONAL: omit it when the customer has a single project (it is inferred); if they have several you get project_id_required — call list_projects and pass one. If categoryMappingNeeded is true, map its categories with list_unmapped_categories + search_target_categories + set_category_mapping (pass the returned feedId as feed_id). The core next step is to MAP output attributes: call get_feed + list_source_attributes, then map_feed_attribute per attribute (category mapping only covers categories, not attributes). Requires the project's data imported (dataStatus='ok', see get_import_status). If this Koongo account cannot hold another feed, the call is refused with error 'quota_reached' (HTTP 403); tell the user it is not available for this account and do not retry.

Create a new marketplace integration for a project from one of the channels in list_marketplace_channels. Use this when the user asks to add a marketplace. channel_code is the channelCode from list_marketplace_channels. Returns {integrationId, action:'create', status, kind:'marketplace', editUrl, nextStepType, message}. status is 'created' (the marketplace exists; continue with configure_marketplace_step starting at nextStepType) or 'prerequisite_not_met' (HTTP 409 — message explains what must be done first, e.g. an offer/primary feed must exist first, another marketplace is not included in this Koongo account (the message explains it), or the primary channel must be created first — see nextStepType). primary_sync marks this as the primary product source; order_sync enables order synchronization if the channel supports it; multichannel_code links a multichannel definition when the channel offers one (see get_marketplace_channel). definition_code picks a SPECIFIC definition of the channel when it has more than one (e.g. Amazon/Kaufland expose 'Offers' AND 'New Products') — take it from get_marketplace_channel definitions[].definitionCode; OMIT it to create the channel's default/primary definition. (versionType primary/secondary in get_marketplace_channel tells the definitions apart; it is NOT the same as primary_sync, which just marks this integration as the primary product source.) name is an OPTIONAL human-readable label so you can later find this marketplace by name (names are not unique — set_marketplace_name can change it later). project_id is OPTIONAL (inferred for a single-project customer; if project_id_required is returned, call list_projects).

Create a NEW product rule (an Attribute Rule). Use this to save a new rule after validate_rule passes. GUARDRAIL: a Rule is never a substitute for per-product enrichment — if you would need MORE THAN 3 text-contains conditions (contains/contains_any/starts_with on a description/title) to derive a value (color, material, gender…), do NOT create a Rule; enrich instead with set_api_source/set_ai_source and map that source attribute (see the server ENRICH guidance). A Rule patches FEED OUTPUT only and writes NOTHING onto the products; if the user asked to enrich the products / add attribute X to the products, use set_api_source/set_ai_source (or ask first) — never substitute a Rule. Always validate_rule it first and fix every error. Pass the full rule document as rule — {name, description, category, icon, rules:[{sortId, enabled, type, conditions, operationGroups:[{mode, parentMode, attributes, operations:[{name, arguments:{key:value}}]}]}]} (see list_rule_transforms for the vocabulary). Any _id/id you include is IGNORED — the server always mints a new one (this tool never overwrites an existing rule; use update_rule for edits). scope selects where it is created: 'project' (default) = the project's own library; 'shared_template' = the reusable shared template library (a template_read_only error means your access cannot write there). Returns {ruleId, scope, status, changed, reason, validation}; status 'created' on success, or 'rejected' with the validation errors when the rule is invalid (HTTP 200, nothing written). SAVE-ONLY: this stores the document and runs none of its transform steps; a new rule has NO effect on any feed until you attach it to a feed attribute with map_feed_attribute (rule_id) and then export_feed; a shared_template rule affects no feed at all until it is used by a project. VALUE/OPTIONS MAPPING: for a map_attribute_value step, search and replace are arrays of {value:''} objects paired by index (NOT plain strings — plain strings save but map nothing, showing empty rows); replace optional. That step is not executed by validate_rule's dry-run (passthrough computedValue) — verify only after a real export/build. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Delete an ad. DESTRUCTIVE and NOT reversible from this surface: it stops syncing, is removed from the list, and ALSO hard-deletes the ad's feeds (channel profiles) — there is no restore tool here, so warn the user that deletion cannot be undone. Use this when the user explicitly asks to delete an ad. Ads are product-listing channels (Google Shopping, Meta catalog, Microsoft, price comparison) for the merchant's physical products, not marketplaces: they publish products to the channel and have no order sync. Confirm with the user first, then call with confirm:true. Without confirm:true the call returns error 'confirm_required' (HTTP 400) and nothing is deleted. Returns {integrationId, action:'delete', status:'deleted', kind:'ads'}. ad_id is from list_ads. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Remove an AI source (its CSV + registration) by code so it is no longer applied on future imports. Use this when the user explicitly asks to remove an AI source. DESTRUCTIVE: confirm with the user first, then call with confirm:true. Without confirm:true this tool returns error 'confirm_required' and nothing is deleted (the gate is enforced here, before the call reaches Koongo). NOTE: the custom_ values already written onto products are NOT immediately erased — they clear on the next import; call run_ai_source_import to clear them now. project_id is OPTIONAL (inferred for a single-project customer). If this feature is not included in this Koongo account, the call is refused with error 'addon_required' (HTTP 403); tell the user it is not available for this account and do not retry. Returns {status:'deleted'|'not_found', code, applied}.

Remove an API source attribute by code from every product so it is no longer applied. Use this when the user explicitly asks to remove an API source. DESTRUCTIVE: confirm with the user first, then call with confirm:true. Without confirm:true this tool returns error 'confirm_required' and nothing is deleted (the gate is enforced here, before the call reaches Koongo). The values clear from products on the next import — call run_api_source_import to clear them now. project_id is OPTIONAL (inferred for a single-project customer). If this feature is not included in this Koongo account, the call is refused with error 'addon_required' (HTTP 403); tell the user it is not available for this account and do not retry. Returns {status:'deleted', code, applied}.

Delete a feed (soft delete — the generated file and config are removed but it can be restored with restore_feed). Use this when the user explicitly asks to delete a feed. DESTRUCTIVE: confirm with the user first, then call with confirm:true. Without confirm:true the call returns error 'confirm_required' (HTTP 400) and nothing is deleted. Returns {feedId, action:'delete', status:'deleted'}. feed_id from list_feeds; project_id OPTIONAL.

Delete a marketplace. DESTRUCTIVE and NOT reversible from this surface: it stops syncing, is removed from the list, and ALSO hard-deletes the marketplace's feeds (channel profiles) and unregisters its webhooks — there is no restore tool here, so warn the user that deletion cannot be undone. Use this when the user explicitly asks to delete a marketplace. Confirm with the user first, then call with confirm:true. Without confirm:true the call returns error 'confirm_required' (HTTP 400) and nothing is deleted. Returns {integrationId, action:'delete', status:'deleted', kind}. marketplace_id is from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Delete a product rule (Attribute Rule) and unlink it from every feed attribute that uses it. Use this when the user explicitly asks to delete a rule. DESTRUCTIVE: a rule may shape a live feed — check its usageCount with list_rules / get_rule first, warn the user, then call with confirm:true. Without confirm:true the call returns error 'confirm_required' and nothing is deleted. Identify the rule by rule_id (from list_rules). scope selects the library: 'project' (default) or 'shared_template' (a template_read_only error means your access cannot write there). Returns {ruleId, scope, status:'deleted', changed, reason, validation}. Any feed that used this rule reverts to its other value source; run export_feed on those feeds to refresh their output. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Turn OFF order syncing for a standalone order connection. Use this when the user wants a connection to stop importing orders. Imported orders and settings stay. Returns {connectionId, action:'configure', status, orderStatus, message}. Undo with activate_order_connection. connection_id is from get_order_overview; project_id OPTIONAL.

Add ORDER SYNC to an existing marketplace — the capability, not the on/off switch. Use this when a marketplace has no order sync yet and the user wants it. Order sync has two layers: the capability (whether the marketplace pulls orders at all, which adds an 'order-settings' wizard step) and the active on/off mode (start_marketplace_order_sync / stop_marketplace_order_sync). This tool turns the CAPABILITY on for a marketplace created without it: it adds the order-settings step and leaves syncing OFF. Only offer it when get_marketplace reports canEnableOrderSync:true (the channel definition allows order sync and the store platform supports orders); otherwise it returns status 'prerequisite_not_met' (HTTP 409). After it succeeds: (1) re-fetch get_marketplace, find the new 'order-settings' step and configure it with configure_marketplace_step (a form step — payload {items:{fieldCode:value}} from the step's fields), then (2) call start_marketplace_order_sync to START syncing. Returns {integrationId, action:'enable_order_sync', status, kind, editUrl, message}; status is 'updated' (added, or already on) or 'prerequisite_not_met'. marketplace_id is from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). Marketplaces only — ads have no order sync.

Trigger a (re)generation of the feed file. Use this to regenerate the output file after saving feed changes. Returns {feedId, action:'export', status, feedStatus}. status is 'queued' (async via the export queue — normal) or 'done'. After this, poll get_feed_status until status becomes 'generated'. feed_id from list_feeds / create_feed; project_id OPTIONAL. Regeneration replaces the existing output file, including files already pulled by channels, and API feeds may auto-submit after export. Confirm this effect with the user before running it.

AD items: force insert — force a fresh insert of the chosen items on the LIVE ad channel. Use this when the user asks to insert specific listings anew. Needs confirm:true after the user agrees. Target item_ids or all_items:true.

MARKETPLACE items: force insert — force a fresh insert of the chosen items on the LIVE marketplace. Use this when the user asks to insert specific listings anew. Needs confirm:true after the user agrees. Target item_ids or all_items:true.

Get the full detail of one ad: identity + state + the configuration wizard steps. CRITICAL — read activationBehavior in the RESULT: 'summary_step_activates_and_submits_all' means activate_ad ACTIVATES the ad and publishes EVERY matching product to the LIVE channel, so to test safely set MANUAL mode FIRST (set_ad_manual_mode) — it then reads 'summary_step_activates_no_auto_submit' and activation auto-submits nothing; 'already_active' = already live. Ads are product-listing channels (Google Shopping, Meta catalog, Microsoft, price comparison) for the merchant's physical products, not marketplaces: they publish products to the channel and have no order sync. Returns {integrationId, projectId, name, channelCode, kind:'ads', definitionCode, status, ready, lastStep, isReady, isConnected, isOverlimit, primarySync, orderSync, productMode, orderMode, taxonomyCode, categoryMappingRequired, connectionStatus, connectionMessage, connectionExpiresAt, steps:[{type, label, sort, index, ready, current, fields:[{code, label, type, required, options, optionsSource, optionsPending, htmlAttributes, value, help, showIf, hiddenIf}]}], editUrl, activationBehavior}. steps describe the setup wizard: 'current' is the next step to configure (via configure_ad_step, targeting it by its index — two steps can share a type) and 'ready' marks completed steps. fields is the step's input schema: for a form/order-settings step, build configure_ad_step payload {items:{code:value}} from it — required marks mandatory fields, options is the allowed value set (value→label), htmlAttributes carry constraints, value is Some field metadata comes from the channel connection and does NOT exist before the auth step is done: optionsPending=true means the option list could not be resolved yet (an empty options array is a state, not permission to send anything), and a disabled field whose default could not be resolved arrives without that flag because you have to supply the value yourself. Do not cache this schema across the auth step — re-read it once the connection exists. the current value. Steps with an empty fields list take a structured payload instead. The connection/auth step (OAuth or credentials) is NOT configurable via MCP: the user completes it in the browser / Koongo UI, and configure_ad_step returns oauth_required / credentials_in_ui for it — terminal, never retry it with a payload. Each ad owns exactly ONE connection (never shared): connectionStatus is its health (NEW / OK / WARNING / ERROR / EXPIRED), connectionMessage/connectionExpiresAt add detail, and test_ad_connection re-checks it live. taxonomyCode is set AUTOMATICALLY from the channel and is READ-ONLY — it cannot be changed via MCP; category mapping (a wizard step) maps your store categories TO this fixed taxonomy, and categoryMappingRequired says whether that step applies. Secrets are never returned. ad_id is the id from list_ads / create_ad. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). Use this to read an ad's configuration; use ad_status for run progress.

List an ad's OUTPUT attributes and how each is currently sourced — the tool for SOLVING THE ATTRIBUTE FORM (the discipline users struggle with). Use this to find required ad attributes that are still unmapped. Returns {integrationId, attributes:[{code, label, required, hidden, valueSource, platformCode, constant, composedValue, defaultPlatformCode, defaultConstant, allowedValues, formatType, ruleId, ruleName, ruleEnabled, priceAttribute, currency, currencyConversionEnabled, configured, stepField}], requiredCount, requiredUnmappedCount, unresolvedCodes}. valueSource is rule|composed|attribute|constant|unmapped (the effective source; a rule attached but ruleEnabled=false does NOT count and the attribute reads 'unmapped'). priceAttribute=true marks a money attribute (formatType price / price_with_delete); currency is its target currency and currencyConversionEnabled whether Koongo converts the value into it (null = not a price attribute). Conversion only matters when the price is in a DIFFERENT currency than the store; if the attribute's name already names a currency (e.g. its label/code contains "EUR") the value is ALREADY in that currency, so set currencyConversionEnabled=false to avoid converting it twice. requiredUnmappedCount is the running count of REQUIRED attributes with no working source — 0 means the form is solved and the ad can build/export; unresolvedCodes lists exactly which ones to fix. Pass only_unresolved:true to get just those rows. To fill one, match the user's attribute label to its code, then map_ad_attribute. ad_id is from Each row also says WHERE its value comes from: configured=true is a mapping of the customer's own, stepField names a wizard form step field that drives it (change it there with configure_ad_step — mapping it here writes an override that beats the step for good), and neither means the value is only the channel definition's default. A default is not a decision: check it against the store's data before trusting it. list_ads. project_id is OPTIONAL (project_id_required otherwise — then call list_projects). IF categoryAttributeWarmup IS PRESENT WITH pending:true THIS LIST IS INCOMPLETE: the channel's category-specific attributes are still downloading, so requiredUnmappedCount and unresolvedCodes are PROVISIONAL — a required attribute that is not in the list yet cannot be counted as unmapped, so the form can look solved when it is not. Poll ad_status until the block is absent or state is 'ready', then read this again before mapping.

Get one ad channel's detail: the integration TYPES it supports and each type's capabilities. Use this to choose the integration type before create_ad. Ads are product-listing channels (Google Shopping, Meta catalog, Microsoft, price comparison) for the merchant's physical products, not marketplaces: they publish products to the channel and have no order sync. Returns {channelCode, label, kind:'ads', devOnly, multichannel, multichannelCode, definitions:[{ definitionCode, type, typeLabel, label, versionType, primary, capabilities:{orderSync, categoryMapping, productFilter, attributeMapping}}]}. versionType is 'primary' or 'secondary' (primary marks the default). Call this before create_ad to choose the right definitionCode for the channel. channel_code is the channelCode from list_ad_channels. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects and pass its project_id).

Get ONE ad listing item with the product's source values and what Koongo last exported for the channel. Use this to check a price or stock complaint for one product: compare the store's values with the exported ones. Returns {itemId, koongoProductId, parentId, productType, status, statusDescription, channelStatus, channelStatusLabel, listingId, listingUrl, itemLocked, lockedReason, source:{sku, name, priceFinalInclTax, priceFinalExclTax, priceOriginalInclTax, priceOriginalExclTax, qty, stockStatus, sourceUpdatedAt, koongoUpdatedAt, deleted}, lastExport:{state, exportedAt, submittedAt, submissionStatus, values:[{code, label, value}], diff:[{code, label, previous, current}], channelValues}, sensitiveGate}. source is null when the product is no longer in the store data. lastExport.state: sent = the exported change was processed, pending = it waits to be sent, failed = the channel refused the last submission, not_exported = nothing exported yet. values are the exported channel attributes (codes differ per channel); diff is what changed in the last export; submittedAt and channelValues exist only for channels that record them. SENSITIVE-GATE: the first call (acknowledge_sensitive absent/false) withholds every product value and returns {sensitiveGate:{confirmationRequired:true, itemCount, fields, kind}} — present that gate to the USER, get their approval, then re-call with acknowledge_sensitive:true. Find item_id with list_ad_items (fulltext = SKU, name, EAN or listing id); ad_id is the integrationId from list_ads. For why the item fails use get_ad_item_report. project_id is OPTIONAL (project_id_required otherwise — then call list_projects).

Get ONE ad listing item's action-log timeline — the sequence of events that acted on the product and its Koongo/channel state at each point, so you can explain WHY an item ended in its current state. Use this to see what happened to one ad listing over time. Returns {itemId, returned, entries:[{createdAt, event, eventLabel, message, messageLabel, operation, operationLabel, koongoStatus, channelStatus}]} newest first. eventLabel/messageLabel/operationLabel are the human-readable rendering the Koongo UI shows (event name, plain-language explanation, operation title); event/message/operation are the raw codes. Entries are process metadata only (no raw product values); an item with no recorded activity yet returns an empty list. item_id is the itemId from list_ad_items (the same id get_ad_item_report uses); pair the two to diagnose a failing product. ad_id is the integrationId from list_ads. project_id is OPTIONAL (project_id_required otherwise — then call list_projects).

Get the full error report of ONE ad listing item (why the product passed/failed): {itemId, koongoProductId, status, statusDescription, channelStatus, channelStatusLabel, channelStatusDescription, reportMessage, reportCode, errors:[{source, field, fieldLabel, message, code, level, additionalInfo, currentValue}], sensitiveGate}. Use this to explain why one ad listing failed. statusDescription/channelStatusLabel/channelStatusDescription and each error's fieldLabel are the human wording the Koongo UI shows; status/channelStatus/field are raw codes. Each error names the offending attribute (field), its source (export = Koongo-side validation, fixable via a mapping/rule change; adapter / api_error = channel-side reject) and severity (level). SENSITIVE: the offending attribute's currentValue is withheld on the first call (returns a sensitiveGate with confirmationRequired:true + the field CODES); show the gate to the user, then re-call with acknowledge_sensitive:true to receive the values. item_id is the itemId from list_ad_items. ad_id is the integrationId from list_ads. project_id is OPTIONAL (project_id_required otherwise — then call list_projects).

Get the validation report for one ad: the aggregated errors and warnings that block or degrade its feed, with fix suggestions. Use this to explain why ad products fail validation. Ads are product-listing channels (Google Shopping, Meta catalog, Microsoft, price comparison) for the merchant's physical products, not marketplaces: they publish products to the channel and have no order sync. The errors are SPLIT into two groups (as in the CP's two separate views). Returns {integrationId, errorCount, warningCount, statusCounts:[{status, count}], listingStatusCounts:[{status, count}], dataCheckErrors:[...], channelErrors:[...]}, where each error is {source, field, message, code, level, count, fixSuggestions:[{type, stepType, label}]}. dataCheckErrors = the pre-submission KOONGO DATA CHECK (feed-generation validation, source='export' — the same the wizard summary/preview shows, produced when the feed is generated BEFORE anything reaches the channel). channelErrors = the ad channel's OWN responses AFTER submission (source='adapter'/'api_error'). errorCount/warningCount are the COMBINED totals across both groups. Data-check errors exist only after a generation has run — finish the wizard, or repair_ad to (re)generate; export is async, so poll ad_status until productsRefreshing AND productsSubmitting are false, then read the report. statusCounts is how many items sit in each koongo processing status (e.g. completed / error / pending); listingStatusCounts the same by channel listing status (e.g. active / rejected / error). level is error|danger(=warning)|info; count is how many products hit that error. fixSuggestions.type is add_category_mapping|fix_settings|rewrite_attribute|exclude_product, and stepType (when set) names the wizard step to open with configure_ad_step. ad_id is the id from list_ads. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Get the allowed OPTION choices (value + label) of a target feed/channel attribute, so you can pick a VALID value for a "Set option" — an attribute that takes a fixed value from its predefined list (select/dropdown attributes like Fastener Type, Availability, Condition…). Use this when an attribute accepts only listed values. Returns {options:[{value, label}], hasMore, nextOffset}. The stored/exported value is the option's value (NOT its label); label is the human-readable text (often equal to value). Two ways to apply a Set option once you pick a value: WITHOUT conditions set the attribute's constant to that value via map_feed_attribute / map_marketplace_attribute / map_ad_attribute (cheapest — no rule needed); CONDITIONALLY build a rule with a setoption operation (operationGroups mode 'set_option', operations [{name:'setoption', arguments:{value:''}}]) — see list_rule_transforms. Empty options = the attribute is not a closed-option attribute (free text — use set_value instead). Page with offset (from nextOffset) while hasMore is true. TARGET: pass EXACTLY ONE of feed_id (a feed, from list_feeds) or integration_id (a marketplace/ad — the marketplace_id/ad_id from list_marketplaces / list_ads). attribute_code comes from get_feed / get_marketplace_attributes / get_ad_attributes. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Get the current category-mapping rules for a taxonomy (store categories → marketplace/taxonomy categories). Use this to read the existing category mapping of a taxonomy. The rule set is SHARED per project + taxonomy_code + locale (every feed on that taxonomy sees it). Address the taxonomy either by feed_id (its taxonomy is used) OR explicitly by taxonomy_code (+ optional taxonomy_locale). Returns {taxonomyCode, taxonomyLocale, rules:[{type, operator, storeCategoryIds, storeCategoryPaths, attribute, value, targetHash, targetPath}], total}. Use list_unmapped_categories to find gaps, search_target_categories to find a target, and set_category_mapping to fill them. project_id is OPTIONAL (inferred for a single-project customer).

Get the full detail of one feed: identity + state + the attribute mapping (how each output column is sourced). Use this to read a feed's configuration and attribute mapping. Returns {feedId, projectId, feedCode, name, feedType, fileFormat, channelCode, status, enabled, taxonomyCode, taxonomyLocale, feedUrl, exportOutOfStock, attributeCount, requiredUnmappedCount, attributes:[{code, label, platformCode, constant, composedValue, required, hidden, valueSource, defaultPlatformCode, defaultConstant, allowedValues, formatType, ruleId, ruleName, ruleEnabled, priceAttribute, currency, currencyConversionEnabled}]}. hidden=true means the attribute is internal and must never be mapped or surfaced in output; valueSource is rule|composed|attribute|constant|unmapped; allowedValues is the closed value set (empty = open). ruleId/ruleName/ruleEnabled describe an attached Attribute Rule (null when none); valueSource is 'rule' only when the rule is ENABLED — an attribute with ruleId set but ruleEnabled=false has a rule attached-but-disabled that does NOT drive its value (it reads as its other source, or 'unmapped'), so surface it and offer to enable it. priceAttribute=true marks a money attribute (formatType price / price_with_delete); currency is its target currency and currencyConversionEnabled whether Koongo converts the value into it (null = not a price attribute) — only relevant when the price is in a DIFFERENT currency than the store; if the attribute's name already names a currency (label/code contains "EUR") the value is ALREADY in it, so set currencyConversionEnabled=false to avoid double conversion. requiredUnmappedCount is how many REQUIRED attributes still have no working source (valueSource='unmapped'); 0 means the attribute form is solved and the feed can export. Map source attributes with map_feed_attribute (see list_source_attributes). The response also includes settings (the feed's channel output settings): currency/number-format (read-only here) plus stock {stockInValue, stockOutValue, stockAvailabilityAttribute} and shipping {shippingDependentAttribute, shippingMethodName, shippingIntervals:[{from,to,cost}]} — the stock and shipping settings are EDITABLE via set_feed_settings. feed_id is the id from list_feeds / create_feed. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). A soft-deleted feed returns error 'feed_deleted' (not 'not_found') — the id is still valid and the feed can be brought back with restore_feed; it just won't appear in list_feeds while deleted. Use get_feed for configuration/mapping and get_feed_status for run progress. Requires the project's data imported (dataStatus='ok', see get_import_status).

Read the CURRENT output of a feed's already-generated file WITHOUT regenerating it — so it works on a read-only connection (unlike export_feed, which regenerates the file and is a write action). Use this to see what a feed currently contains: its live download URL, product count and a sample of the actual rows, without downloading the file and counting it yourself. Inputs: feed_id (the feed's id from list_feeds / create_feed), project_id (OPTIONAL — inferred for a single-project customer; project_id_required if they have several, then call list_projects), sample_size (default 20, max 20), offset (default 0 — skip this many rows to read a deeper page; page by increasing offset in steps of sample_size). Returns {feedId, projectId, feedCode, fileFormat, feedUrl, fileExists, fileSize, productsCount, lastGeneratedAt, sampleRowCount, sample:[{field: value}, ...]}. feedUrl is the public download URL of the current file; productsCount is exactly the number of rows in that file; lastGeneratedAt is when it was last generated. fileExists:false means the feed has not been generated yet — call export_feed, then poll get_feed_status until it is generated. The sample rows are real feed data returned only after you set acknowledge_sensitive:true. The first call (flag absent/false) returns {sensitiveGate:{confirmationRequired:true, itemCount, fields, kind}} with sample EMPTY (all the metadata is still returned) — present that gate to the USER, get approval, then re-call with acknowledge_sensitive:true to receive the rows.

Get the runtime status of one feed: generation state, progress, last run/submit and any error. Use this to check whether a feed export or submission has finished. Returns {feedId, projectId, feedCode, status, enabled, progressPercent, productsCount, lastRunAt, submitStatus, lastSubmitAt, fileExists, errorMessage}. status is one of new|pending|processing|generated|submited|error|overlimit. Next action per status: generated → verify_feed_attributes then submit_feed; processing/pending → keep polling; error → read errorMessage, fix, export_feed; overlimit → the feed has more products than this Koongo account includes. Use get_feed for configuration/mapping and this tool for run progress. feed_id is the id from list_feeds / create_feed. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Check whether a project's store data is connected, imported and fresh before advising on feeds/mapping. Use this to confirm the store data is ready before mapping or creating feeds. Returns {projectId, code, apiStatus, dataStatus, lastImportAt, progressPercent, productsCount, categoriesCount, lastRun:{...}, recentRuns:[{status, type, startedAt, endedAt, productTotal, productsAvailable, errorMessage, importTimeSeconds, running}]}. apiStatus is GRANTED|REVOKED|OVERLIMIT; dataStatus is not_imported|pending|processing|ok|error|suspend|stopped (the project-wide state — map only when 'ok'). recentRuns lists the latest runs newest-first, each tagged by type (normal|partial|api_source|additional_source|upgrade) and running (true while pending/processing); lastRun is the newest of them. Use recentRuns to verify a specific enrichment import: after run_api_source_import / run_ai_source_import, poll here until the newest run of that type (api_source for set_api_source, additional_source for set_ai_source) has running:false and status 'ok' — THEN the new attribute is available in list_source_attributes / list_api_sources and you can map it or continue the integration. A run with status 'error' → read its errorMessage and call the same import tool again to retry. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). When dataStatus='ok', proceed to preview_products then list_feed_templates.

Get Koongo help topics: glossaries and deep-detail reference kept out of the server instructions. Use this when you need to interpret a marketplace/ad listing status or item status (from list_*items / get*_item_report / *_status / *_report), or need the reference for the product filter, value/options mapping, currency conversion, or safe activation. Call with no args for the topic index (slug + title + summary); with slug for one topic's full body (plus a canonical help url when available); with query to keyword-search the corpus. Topics: listing-and-item-status, product-filter, value-and-options-mapping, currency-conversion, safe-activation, marketplace-wizard-steps, ad-wizard-steps, rule-authoring. Read-only.

Get the full detail of one marketplace: identity, state and wizard steps. Use this to read its configuration. CRITICAL — read activationBehavior in the RESULT: 'summary_step_activates_and_submits_all' means activate_marketplace ACTIVATES the marketplace and publishes EVERY matching product to the LIVE channel, so to test safely set MANUAL mode FIRST (set_marketplace_manual_mode) — it then reads 'summary_step_activates_no_auto_submit' and activation auto-submits nothing; 'already_active' = already live. Returns {integrationId, projectId, name, channelCode, kind, definitionCode, status, ready, lastStep, isReady, isConnected, isOverlimit, primarySync, orderSync, canEnableOrderSync, productMode, orderMode, taxonomyCode, categoryMappingRequired, connectionStatus, connectionMessage, connectionExpiresAt, steps:[{type, label, sort, index, ready, current, fields:[{code, label, type, required, options, optionsSource, optionsPending, htmlAttributes, value, help, showIf, hiddenIf}]}], editUrl, activationBehavior}. steps describe the setup wizard: 'current' is the next step to configure (via configure_marketplace_step, targeting it by its index — two steps can share a type) and 'ready' marks completed steps; fields is that step's input schema. Do not cache this schema across the auth step: field metadata from the channel connection (options, resolved defaults) does not exist before it. The connection/auth step (OAuth or credentials) is NOT configurable via MCP — the user completes it in the browser / Koongo UI. taxonomyCode is set automatically from the channel and is read-only. Full field-by-field reference (step payloads, optionsPending, connection health, category mapping, order sync, marketplace_status): call get_koongo_help with slug 'marketplace-wizard-steps'. marketplace_id is the id from list_marketplaces / create_marketplace. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

List a marketplace's OUTPUT attributes and how each is currently sourced — the tool for SOLVING THE ATTRIBUTE FORM (the discipline users struggle with). Use this to find required marketplace attributes that are still unmapped. Returns {integrationId, attributes:[{code, label, required, hidden, valueSource, platformCode, constant, composedValue, defaultPlatformCode, defaultConstant, allowedValues, formatType, ruleId, ruleName, ruleEnabled, priceAttribute, currency, currencyConversionEnabled, configured, stepField}], requiredCount, requiredUnmappedCount, unresolvedCodes}. valueSource is rule|composed|attribute|constant|unmapped (the effective source; a rule attached but ruleEnabled=false does NOT count and the attribute reads 'unmapped'). priceAttribute=true marks a money attribute (formatType price / price_with_delete); for those, currency is its target currency and currencyConversionEnabled whether Koongo converts the value into it (null = not a price attribute). Currency conversion only matters when the price is in a DIFFERENT currency than the store; if the attribute's name already names a currency (e.g. its label/code contains "EUR") the value is ALREADY in that currency, so set currencyConversionEnabled=false to avoid converting it twice. requiredUnmappedCount is the running count of REQUIRED attributes with no working source — 0 means the form is solved and the integration can build/export; unresolvedCodes lists exactly which ones to fix. Pass only_unresolved:true to get just those rows. To fill one, match the user's attribute label to its code, then map_marketplace_attribute. Each row also says WHERE its value comes from: configured=true is a mapping of the customer's own, stepField names a wizard form step field that drives it (change it there with configure_marketplace_step — mapping it here writes an override that beats the step for good), and neither means the value is only the channel definition's default. A default is not a decision: check it against the store's data before trusting it. marketplace_id is from list_marketplaces. project_id is OPTIONAL (project_id_required otherwise — then call list_projects). IF categoryAttributeWarmup IS PRESENT WITH pending:true THIS LIST IS INCOMPLETE: the channel's category-specific attributes are still downloading, so requiredUnmappedCount and unresolvedCodes are PROVISIONAL — a required attribute that is not in the list yet cannot be counted as unmapped, so the form can look solved when it is not. Poll marketplace_status until the block is absent or state is 'ready', then read this again before mapping.

Get, for ONE marketplace channel, the integration TYPES it supports and each type's capabilities. Use this to choose the integration type before create_marketplace. Returns {channelCode, label, kind, devOnly, multichannel, multichannelCode, definitions:[{definitionCode, type, typeLabel, label, versionType, primary, capabilities:{orderSync, categoryMapping, productFilter, attributeMapping}}]}. kind is always 'marketplace' here. versionType is 'primary' or 'secondary' and primary marks the default definition. capabilities tell you what a given definition supports (order sync, category mapping, product filtering, attribute mapping). Call this before create_marketplace to choose the right definition for the channel. channel_code is the channelCode from list_marketplace_channels. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects and pass its project_id).

Get ONE marketplace listing item with the product's source values and what Koongo last exported for the channel. Use this to check a price or stock complaint for one product: compare the store's values with the exported ones. Returns {itemId, koongoProductId, parentId, productType, status, statusDescription, channelStatus, channelStatusLabel, listingId, listingUrl, itemLocked, lockedReason, source:{sku, name, priceFinalInclTax, priceFinalExclTax, priceOriginalInclTax, priceOriginalExclTax, qty, stockStatus, sourceUpdatedAt, koongoUpdatedAt, deleted}, lastExport:{state, exportedAt, submittedAt, submissionStatus, values:[{code, label, value}], diff:[{code, label, previous, current}], channelValues}, sensitiveGate}. source is null when the product is no longer in the store data. lastExport.state: sent = the exported change was processed, pending = it waits to be sent, failed = the channel refused the last submission, not_exported = nothing exported yet. values are the exported channel attributes (codes differ per channel); diff is what changed in the last export; submittedAt and channelValues exist only for channels that record them. SENSITIVE-GATE: the first call (acknowledge_sensitive absent/false) withholds every product value and returns {sensitiveGate:{confirmationRequired:true, itemCount, fields, kind}} — present that gate to the USER, get their approval, then re-call with acknowledge_sensitive:true. Find item_id with list_marketplace_items (fulltext = SKU, name, EAN or listing id); marketplace_id is the id from list_marketplaces. For why the item fails use get_marketplace_item_report. project_id is OPTIONAL (project_id_required otherwise — then call list_projects).

Get ONE listing item's action-log timeline — the sequence of events that acted on the product and its Koongo/channel state at each point, so you can explain WHY an item ended in its current state (e.g. it was created, changed, validated, pre-paired, submitted, rescheduled, removed, locked). Use this to see what happened to one marketplace listing over time. Returns {itemId, returned, entries:[{createdAt, event, eventLabel, message, messageLabel, operation, operationLabel, koongoStatus, channelStatus}]} newest first. eventLabel/messageLabel/operationLabel are the human-readable rendering the Koongo UI shows (event name, plain-language explanation, operation title); event/message/ operation are the raw codes. Entries are process metadata only (no raw product values). item_id is the itemId from list_marketplace_items (the same id get_marketplace_item_report uses). Pair this with get_marketplace_item_report (current errors) to diagnose a failing product. marketplace_id is the integrationId from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Get the detailed report for ONE listing item of a marketplace: why this product fails or warns on the channel. Use this to explain why one marketplace listing failed. Returns {itemId, koongoProductId, status, statusDescription, channelStatus, channelStatusLabel, channelStatusDescription, reportMessage, reportCode, errors:[{source, field, fieldLabel, message, code, level, additionalInfo, currentValue}], sensitiveGate}. statusDescription/channelStatusLabel/ channelStatusDescription and each error's fieldLabel are the human wording the Koongo UI shows (status + attribute name); status/channelStatus/field are the raw codes. source is export|adapter|api_error; level is error|danger(=warning)|info. currentValue is the offending value that was sent to the channel. SENSITIVE-GATE: currentValue exposes real product data, so the first call (acknowledge_sensitive absent/false) returns the report with currentValue withheld and a {sensitiveGate:{confirmationRequired:true, itemCount, fields, kind}} — present that gate to the USER, get their approval, then re-call with acknowledge_sensitive:true to receive the actual values. item_id is the id from list_marketplace_items; marketplace_id is the id from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). For the marketplace-wide breakdown use get_marketplace_report.

Get the validation report for one marketplace: the aggregated errors and warnings that block or degrade its listing, with fix suggestions. Use this to explain why marketplace products fail validation. The errors are SPLIT into two groups (as in the CP's two separate views). Returns {integrationId, errorCount, warningCount, statusCounts:[{status, count}], listingStatusCounts:[{status, count}], dataCheckErrors:[...], channelErrors:[...]}, where each error is {source, field, message, code, level, count, fixSuggestions:[{type, stepType, label}]}. dataCheckErrors = the pre-submission KOONGO DATA CHECK (feed-generation validation, source='export' — the same the wizard summary/preview shows, produced when the feed is generated BEFORE anything reaches the channel). channelErrors = the marketplace's OWN responses AFTER submission (source='adapter'/'api_error' — the integration detail). errorCount/warningCount are the COMBINED totals across both groups. Data-check errors exist only after a generation has run — finish the wizard, or repair_marketplace to (re)generate; export is async, so poll marketplace_status until productsRefreshing AND productsSubmitting are false, then read the report. statusCounts is how many items sit in each koongo processing status (e.g. completed / error / pending); listingStatusCounts the same by channel listing status (e.g. active / rejected / error). level is error|danger(=warning)|info; count is how many products hit that error. fixSuggestions.type is add_category_mapping|fix_settings|rewrite_attribute| exclude_product, and stepType (when set) names the wizard step to open with configure_marketplace_step. This is the marketplace-wide breakdown; for a single product's report use get_marketplace_item_report. marketplace_id is the id from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Full detail of ONE standalone order connection, including its Orders Config form. Use this to read an order connection's settings before changing them. Returns {connectionId, name, channelCode, channelLabel, channelApiCode, status, orderStatus, orderSyncLevel, authType, connected, expired, hasCredentials, authMessage, lastSyncStatus, lastSyncAt, lastSyncMessage, ordersThisMonth, orderConfigFields:[{code, label, description, type, required, options, optionsSource, value, defaultValue, adminOnly, locked}]}. A field with locked:true is not included in this Koongo account and cannot be set; options may be null for a field whose choices are only known after the connection is authenticated. Use orderConfigFields to build a configure_order_connection call. connection_id is from get_order_overview. ONLY standalone order connections (from get_order_overview): a connectionId taken from list_orders for a marketplace integration answers 404 here; that is expected, not a broken connection. project_id is OPTIONAL (project_id_required otherwise — then call list_projects).

Get the browser setup link for a new standalone order connection, using a channel from list_order_channels. Use this when the user wants to add a standalone order connection. It only reads the channel and the account; it does not create a connection, save credentials or start OAuth. Returns status:'auth_required' and authUrl when this connection is included in the Koongo account; otherwise returns status:'rejected' without a link and a message: not included in this Koongo account → tell the user and stop; could not be confirmed right now → try again later; the channel does not support order connections → pick a channel from list_order_channels. The user completes authentication in the browser. Afterwards use get_order_overview, test_order_connection and configure_order_connection. project_id is optional for a single-project account.

The project's ORDER dashboard for standalone order connections (marketplaces managed WITHOUT a product wizard). Use this to see the project's order connections and their sync status. Returns order counts and the project's order connections in one call: {ordersToday, ordersThisMonth, ordersLastMonth, ordersLast12Months, ordersWithError, ordersNotInserted, activeConnectionCount, syncStatus, syncStatusLabel, syncStartedAt, syncedAt, syncMessage, connections:[{connectionId, name, channelCode, channelLabel, channelApiCode, status, orderStatus, orderSyncLevel, authType, hasCredentials, lastSyncStatus, lastSyncAt, lastSyncMessage}]}. orderStatus is 'active'|'disabled'|'not allowed'|'overlimit' (whether that connection is syncing orders). Start here to see order state, then drill into one connection with get_order_connection. A newly added connection appears here once the user finishes authentication in the Koongo UI. Marketplace integrations with order sync are NOT listed here; see marketplace_status. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Get a project's catalog product profile so you can suggest suitable sales channels for it. Use this when the user asks which sales channels fit their catalog. Returns {projectId, marketCategories:[{name, score, source}], stats:{productsCount, productsTotal, categoriesCount, avgPrice, medianPrice, currency, eanFillRate, eanBucket, metricsSyncedAt}}. marketCategories is the AI-detected catalog VERTICAL, ordered by score DESC — the first is the dominant vertical (e.g. 'Fashion & Accessories', 'Home & Decoration'); score is 0–1 confidence, source is ai|manual; the list is empty when the catalog has not been categorised yet. stats are catalog aggregates: avgPrice/medianPrice are in currency; eanFillRate is the 0–1 EAN/GTIN coverage and eanBucket its coarse form none|low|medium|high; a null means not-yet-computed (metricsSyncedAt shows how fresh the price/EAN figures are). Use the dominant vertical + price band + EAN coverage to suggest fitting marketplaces/ads: cross-reference list_marketplace_channels / list_ad_channels and propose ONLY channels whose available is true, then walk the create/configure wizard. Never invent channels that aren't in the catalog. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Get the full definition of one product rule (Attribute Rule), including its verbatim rules[] (round-trippable — you can edit it and pass it back to update_rule). Use this to read a rule before changing or reusing it. Returns {ruleId, name, description, category, scope, rules, createdAt, updatedAt}. rules[] is {sortId, enabled, type, conditions, operationGroups:[{mode, parentMode, attributes, operations:[{name, arguments}]}]} (see list_rule_transforms). scope selects the library: 'project' (default) or 'shared_template'. An unknown rule_id returns error 'not_found'. rule_id is from list_rules. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Get the inputs needed to build a value-mapping rule (Attribute Rule) that remaps a source attribute's values onto a target attribute's allowed set (e.g. store colours → the channel's accepted colour list). Use this to collect the inputs of a value-mapping rule before building it. Works for BOTH a feed and a marketplace/ad. This is for value→value MAPPING (the map_attribute_value operation); to just assign ONE fixed value from an attribute's option list (a "Set option") use get_attribute_options instead. Returns {sourceValues:[{value, label}], targetAllowedValues:[{value, label}], alreadyMapped:[{search, replace}], hasMore, nextOffset}. sourceValues are the distinct values of source_attribute_code in the store; targetAllowedValues are the values target_attribute_code accepts on the target; alreadyMapped are the pairs already configured. YOU propose the search→replace pairs from these two lists — this tool runs no AI and never writes. Apply the pairs by adding a map_attribute_value operation (arguments search/replace) to the rule via create_rule / update_rule, then attach the rule (map_feed_attribute / map_marketplace_attribute / map_ad_attribute with rule_id); values you leave unmapped pass through unchanged for the user to finish manually. search/replace on the map_attribute_value op you build from these are arrays of {value:''} objects paired by index (NOT plain strings). Pass only_unmapped:true to get only source values that still need a pair; page with offset (from nextOffset) while hasMore is true. TARGET: pass EXACTLY ONE of feed_id (a feed, from list_feeds) or integration_id (a marketplace/ad — the marketplace_id/ad_id from list_marketplaces / list_ads); integration_id resolves the integration's attributes. The attribute codes come from get_feed / get_marketplace_attributes / get_ad_attributes / list_source_attributes. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). This tool returns real store data values only after you set acknowledge_sensitive:true. The first call (flag absent/false) returns {sensitiveGate:{confirmationRequired:true, itemCount, fields, kind}} with the sourceValues / alreadyMapped arrays EMPTY — present that gate to the USER, get their approval, then re-call with acknowledge_sensitive:true to receive the actual values.

Search the CATALOG of ADS channels you can ADD — product-listing channels (Google Shopping, Meta catalog, Microsoft, Pinterest, …) you can create an ads integration for (to list the ads that ALREADY exist, use list_ads). Use this when the user wants to add an ad channel and needs its channelCode. Ads are product-listing channels for the merchant's physical products, not marketplaces: they publish products to the channel and have no order sync. SEARCHABLE + PAGED: pass query to match a channelCode/label, page with limit/offset (response carries hasMore + nextOffset). Response = {channels, returned, total, kind, hasMore, nextOffset}; each channel = {channelCode, label, kind, available, availabilityReason, authType, orderSyncSupported, multichannel, multichannelCode, primaryChannelCode, devOnly, feedManagerUrl}. available=false → availabilityReason says why: 'not_included' or another reason (not available for this Koongo account). orderSyncSupported is always false for ads. Use channelCode with get_ad_channel (definition types + capabilities) then create_ad. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

AD items — list the individual listing items of one ADS integration, the per-product rows for listing-based ad channels (e.g. Marktplaats and other classifieds, which create one ad per product). Use this to find individual ad listings and their status. Some ad channels (e.g. Google Shopping) submit the whole product set in bulk rather than as individual listings and so have no per-item rows — they return an empty list; use ad_status / get_ad_report for those. Returns {integrationId, total, returned, items:[{itemId, koongoProductId, parentId, productType, status, channelStatus, listingId, listingUrl, hasErrors, errorCount}], searchStatus}. Filter with koongo_status, channel_status, listing_id or product_id to find failures, or find a product with fulltext (SKU, name, EAN, listing id); page with limit / offset. Rows carry only identifiers + statuses (no gate); an item's actual attribute value + full error report come from get_ad_item_report. itemId is what you pass to get_ad_item / get_ad_item_report / get_ad_item_history. ad_id is the integrationId from list_ads. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

List the CREATED ads of a project (the ad integrations that already exist, not the catalog of channels you can add — use list_ad_channels for that). Use this to find an existing ad and its ad_id. Ads are product-listing channels (Google Shopping, Meta catalog, Microsoft, price comparison) for the merchant's physical products, not marketplaces: they publish products to the channel and have no order sync. Returns {integrations, returned, total}; each row is {integrationId, projectId, name, channelCode, kind:'ads', definitionCode, status, ready, lastStep, isReady, isConnected, isOverlimit, productMode, orderMode, orderSync}. project_id is OPTIONAL: with it you get that project's ads; WITHOUT it you get ads across ALL your projects (each row carries its projectId). If a call returns project_id_required, pick a project (see list_projects) and pass its project_id. integrationId is what you pass as ad_id to get_ad / ad_status and the other ads tools.

List the AI sources currently registered on a project (attributes populated via set_ai_source). Use this to see which AI sources a project already has. Returns {items:[{code, url, handle}]} — code is the attribute name (available as custom_ once applied), handle the product key it joins on. project_id is OPTIONAL (inferred for a single-project customer).

List the API source attribute codes registered on a project (populated via set_api_source; usable in rules as api_source.). Use this to see which API source attributes a project has. Returns {codes:[...], addonAvailable}: addonAvailable is false when API sources are not included in this Koongo account, so set_api_source would be refused; tell the user it is not available for this account. project_id is OPTIONAL (inferred for a single-project customer).

List the customer's CREATED feeds (the feeds that already exist, not the catalog of types — use list_feed_templates for that). Use this to find an existing feed and its feedId. Each item is {feedId, projectId, feedCode, name, feedType, fileFormat, channelCode, status, feedUrl, lastRunAt}. project_id is OPTIONAL: with it you get that project's feeds; WITHOUT it you get your feeds across ALL your projects (each item carries its projectId). If a call returns project_id_required, pick a project (see list_projects) and pass its project_id. feedId is the per-project id you pass as feed_id to get_feed / verify_feed_attributes. Integration-managed feeds are excluded; only standalone feeds are returned. Returns all matching feeds in one call; not paginated. byChannel:[{projectId, channelCode, count, statuses:{:n}}] (largest first) gives feed counts per project and channel — quote those, never count the list yourself; without project_id, filter by projectId before quoting a count for one project.

List the PUBLIC Koongo feed TEMPLATES available for a project — the catalog of feed TYPES you can create from (the feedCode source for create_feed). Use this when the user wants a new feed and you need its feedCode. These are NOT the customer's existing feeds (use list_feeds for those). Each item is {feedCode, name, type, fileType, channelCode, country}. project_id is OPTIONAL: omit it when the customer has a single project (it is inferred); if they have several you get project_id_required — call list_projects and pass one. Pass query as a BROAD coarse filter — ideally just the channel/marketplace name (e.g. 'google'); do NOT put country/format/language words in it, because feed codes are cryptic and a literal match will miss. Instead match the user's request (country e.g. CZ/Czech/Česko, format e.g. xml, type e.g. product vs promotions) against the STRUCTURED fields of the returned items yourself — word order and synonyms don't matter. Show the closest matches, let the user confirm which feedCode, then call create_feed. Returns all matching templates in one call; not paginated.

Search the CATALOG of marketplace channels you can ADD — every sales channel (Amazon, eBay, Kaufland, Bol, Zalando, comparison sites, …) you can create a marketplace integration for (to list the marketplaces that ALREADY exist, use list_marketplaces). Use this when the user wants to add a marketplace and needs its channel. The catalog is large (many country variants), so it is SEARCHABLE + PAGED: pass query to match a channelCode/label (e.g. "amazon"), and page with limit/offset (the response carries hasMore + nextOffset). Response = {channels, returned, total, kind, hasMore, nextOffset}; each channel = {channelCode, label, kind, available, availabilityReason, authType, orderSyncSupported, multichannel, multichannelCode, primaryChannelCode, devOnly, feedManagerUrl}. available=false means you cannot add it now and availabilityReason says why: 'not_included' or another reason (not available for this Koongo account), or 'fallback' (feedManagerUrl — connect it via Feed Manager). authType is oauth|credentials|null. Use channelCode with get_marketplace_channel (to see the definition types + capabilities) and then create_marketplace. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

MARKETPLACE items — list the individual listing items of one marketplace, the per-product rows of what is (or should be) listed on the channel. Use this to find individual marketplace listings and their status. Applies to marketplace integrations. Returns {integrationId, total, returned, items:[{itemId, koongoProductId, parentId, productType, status, channelStatus, listingId, listingUrl, hasErrors, errorCount}], searchStatus}. status is the Koongo-side listing state; channelStatus is the channel's own state; listingId / listingUrl are the item's identity on the channel. Rows carry only identifiers and statuses — never a raw product attribute VALUE — so no confirmation is needed here; to see an item's actual attribute value plus its full error report, use get_marketplace_item_report (which gates the value behind a user confirmation). Filter with koongo_status (e.g. the failed items), channel_status, listing_id or product_id to drive a fix, or find a product with fulltext (SKU, name, EAN, listing id; searchStatus ok|capped|timeout|error); page with limit / offset. itemId is what you pass as item_id to get_marketplace_item_report / get_marketplace_item. marketplace_id is the id from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

List the CREATED marketplace integrations of a project — the marketplace integrations that already exist, not the catalog of channels you can add (use list_marketplace_channels for that). Use this to find an existing marketplace and its marketplace_id. Each item is {integrationId, projectId, name, channelCode, kind, definitionCode, status, ready, lastStep, isReady, isConnected, isOverlimit, productMode, orderMode, orderSync}. The response wrapper is {integrations, returned, total}. project_id is OPTIONAL: with it you get that project's marketplaces; WITHOUT it you get marketplaces across ALL your projects (each item carries its projectId). If a call returns project_id_required, pick a project (see list_projects) and pass its project_id. integrationId is what you pass as marketplace_id to get_marketplace / marketplace_status and the other marketplace tools.

List the marketplaces that can be added as a standalone ORDER connection — order-capable channels that do NOT have a product wizard. Use this when the user wants to add a standalone order connection. (Channels that DO have a wizard are added with create_marketplace instead, not here.) Returns {channels:[{channelApiCode, label, channelCode, logoUrl, authType ('oauth'|'api_key'), available}], total}. 'available' is false when the project already has as many order connections as this Koongo account includes; get_order_connection_setup_link makes the final check. Pass a channelApiCode to get_order_connection_setup_link to start adding one. Optional query filters by name/code. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

List the ORDER COMMANDS of the project — the sync steps behind each order: insert_order (into the store), update_order, accept_order, cancel_order, add_shipment (tracking to the channel), add_invoice, add_refund, decrease_stock and others. Use this to find which step of an order failed, when and why, e.g. an order that did not reach the shop or a tracking number that did not reach the marketplace. Returns {commands:[{commandId, orderId, commandCode, commandLabel, status, publisher, publisherId, subscriber, subscriberId, createdAt, updatedAt, processAfter, errorCode, message}], returned, statusCounts:[{commandCode, status, count}], countsComplete, sensitiveGate}, most recently created first. status: new / pending / processing / pending_result = waiting or running; complete = done; error = failed (retried at processAfter); warning / skipped / not_available = finished without effect. publisher issued the step and subscriber runs it (store / channel / core), publisherId and subscriberId name the platform or channel; errorCode is Koongo's error code. statusCounts counts the newest 5000 matching commands; countsComplete:false = partial. Filter by order_id (orderId from list_orders; wins over channel_order_id), status, command_code, since (YYYY-MM-DD, created or updated on or after); limit default 50, max 200. A broad filter on a large project can return invalid_request query_timeout: add status, order_id or since. SENSITIVE-GATE: message (redacted error text that can quote customer data) is null until acknowledge_sensitive:true; the first call returns {sensitiveGate:{confirmationRequired:true, itemCount, fields:['message'], kind:'order_messages'}} — present it to the USER, get approval, then re-call. project_id is OPTIONAL (project_id_required otherwise — then call list_projects).

List recent order records for the project, PII-FREE — customer name, e-mail, phone and billing/shipping addresses are never returned. Use this to find orders and spot ones that failed to sync. To spot sync problems, pass errors_only:true to see only orders that failed or were not inserted. Optional connection_id restricts to one order connection; limit caps the result (default 50, max 200). Returns {orders:[{orderId, channelOrderId, channelOrderName, storeOrderId, connectionId, channelCode, marketplaceCode, status, syncStatus, createdAt}], total}. syncStatus flags which orders failed ('error'/'not_inserted'); to see WHICH sync step failed, when and why, pass orderId as order_id to list_order_commands. connectionId of an order from a marketplace INTEGRATION (marketplaceCode set) is not a standalone order connection: get_order_connection / get_order_overview do not know it and answer 404 — that does NOT mean the connection is broken or deleted. For those orders use list_marketplaces (match marketplaceCode/channelCode), marketplace_status (orderStats) and sync_marketplace_orders. project_id is OPTIONAL (project_id_required otherwise — then call list_projects).

List your projects. Each item is {projectId, code, name, apiStatus, dataStatus, language, customerId, customerEmail, platformCode, platformName}. Use this to find the project a request is about, before other tools. platformCode is the shop's e-commerce platform (shopify, magento_2, woocommerce, ...) when the control panel reports one; setup and available integrations differ by it. Call this FIRST when you don't know which project to act on, or when another tool returns project_id_required. Let the user pick, then pass the chosen projectId to the other tools. When you own a single project you usually don't need this — the other tools infer it. Pass query to search projects by name, code, or owner email. Note: if the call returns an EMPTY list, do not assume there are no projects — some accounts only return projects that MATCH a search term, so ask the user what to look for (a project name/code or the owner's email) and retry with a query. A broad search may be capped, so keep the query specific. apiStatus GRANTED = active; REVOKED/OVERLIMIT projects are listed too so the user sees them. After the user picks, the usual next step is get_import_status for that projectId.

List the product rules (Attribute Rules) available to a project. Use this to find an existing rule and its ruleId. Returns {rules:[{ruleId, name, description, category, scope, usageCount}], returned, total}. usageCount is how many feed attributes currently use the rule. scope selects which library to list: 'project' (default) = the project's own rules; 'shared_template' = the reusable shared template library; 'all' = both. Optionally pass query: a case-insensitive SUBSTRING match on the rule NAME only (a coarse pre-filter — rule names are not unique, so confirm the match yourself and disambiguate when more than one matches). Use get_rule to fetch a rule's full rules[]. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). Returns all rules in one call (returned === total); not paginated.

List the transform steps and condition operators a product rule may use (an attribute-value transformation — the feature Koongo's UI and help call "Attribute Rules" / "Rules"). Use this to look up the vocabulary FIRST, before you write a rule. Read-only reference data: a transform step (trim, replace text, map values…) is a pure value transformation stored in a rule document and applied when Koongo builds a feed — not an action any tool runs. GUARDRAIL: a Rule must never be keyword-matching — if a value would need MORE THAN 3 text-contains conditions to derive (color, material, gender… from free text), STOP and enrich per-product with set_api_source/set_ai_source; do not build the Rule. A Rule patches FEED OUTPUT only and writes NOTHING onto the products; if the user asked to enrich the products, use set_api_source/set_ai_source (or ask first) — never substitute a Rule. Returns {operations:[{name, label, group, returnType, valueType, arguments}], conditions:[{operator, label, disabledFor, arguments}], ruleSchema, examples} — operations is the rule document's key for its transform steps. Filter to one step group with group; set detail 'full' for the complete argument specs and 'compact' (default) for a lighter list. include_conditions adds the condition operators; include_examples adds curated end-to-end worked examples. Steps in a group run left-to-right; each step's returnType must match the next step's valueType. str_replace searches LITERAL text (., *, | mean themselves) unless the search has regex delimiters, like /\s*\|.*$/. Full authoring recipe — the rule-document and condition-tree shape, sortId precedence and the Default Rule, matching a condition value's type to its attribute, and the map_attribute_value (search/replace as ARRAYS OF OBJECTS {value:'…'} paired by index — the #1 gotcha) and setoption recipes: call get_koongo_help with slug 'rule-authoring'. Always validate_rule a rule before create_rule / update_rule.

List the source attributes the store provides that a feed column can be mapped from (the valid platform_code values for map_feed_attribute) — e.g. brand, ean, price, color, category_name. Use this to find the source attribute codes a mapping can use. Returns {attributes:[{code, label, dataType}], returned, total}. Pass feed_id for full parity with the feed editor (adds the feed's taxonomy_* attributes); project_id alone omits taxonomy. Call this BEFORE map_feed_attribute to choose a valid platform_code. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). Requires the project's data imported (dataStatus='ok', see get_import_status). Returns all attributes in one call (returned === total); not paginated.

List the project's store categories (the source side of category mapping and of a feed's category filter). Use this to read the store's category tree. Returns {categories:[{id, name, path}], returned, total, hasMore, nextOffset}; path is the full breadcrumb (e.g. "Electronics > Computers > Laptops"). Use the ids with set_category_mapping (map store categories to a marketplace category) or set_feed_filter (category_ids). project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). Paginated: default limit 200, max 1000. When hasMore is true, call again with offset = nextOffset and keep paging until hasMore is false to see every category.

List the project's store categories that have NO mapping rule yet for a taxonomy — the gaps to map. Use this to find store categories that still need a mapping. Address the taxonomy by feed_id (its taxonomy is used) OR explicitly by taxonomy_code (+ optional taxonomy_locale). Returns {categories:[{id, name, path}], returned, total, taxonomyCode, taxonomyLocale, hasMore, nextOffset}. For each gap, find a target with search_target_categories and map it with set_category_mapping. project_id is OPTIONAL (inferred for a single-project customer). Paginated: default limit 200, max 1000. When hasMore is true, call again with offset = nextOffset and keep paging until hasMore is false to see every gap.

AD items: lock — keep the chosen items unchanged by automatic sync (undo: unlock_ad_items). Use this when the user wants listings frozen. Needs confirm:true after the user agrees. Target item_ids or all_items:true.

MARKETPLACE items: lock — keep the chosen items unchanged by automatic sync (undo: unlock_marketplace_items). Use this when the user wants listings frozen. Needs confirm:true after the user agrees. Target item_ids or all_items:true.

Set where ONE of an ad's output attributes gets its value — the write half of solving the attribute form. Use this to fill or change one ad output attribute. Target the output attribute by code (from get_ad_attributes). Set platform_code to a source attribute (from list_source_attributes) to map it, and/or constant for a fixed value; default_platform_code / default_constant are the fallback used when the primary source is empty. For an IDENTIFIER (sku, gtin/ean/barcode, mpn), first confirm the chosen source is actually populated across the catalog (get_project_profile eanFillRate; page preview_products) — mapping or requiring an identifier the products lack yields an empty, non-functional integration. rule_id attaches an Attribute Rule (from list_rules / create_rule) — the value is then computed by that rule; send rule_id:"" to detach it, and rule_enabled:false to attach it disabled. To re-enable an attached-but-disabled rule, send rule_enabled:true (with or without its rule_id, from get_ad_attributes). rule_enabled on its own applies to whatever rule is already attached; with none attached it is rejected as unknown_rule. Provide at least one field (send an empty string to clear a text field). rule_id together with platform_code/constant in the same call is contradictory and is rejected. Setting a source (platform_code/constant) on an attribute that currently has a rule DETACHES that rule (mutually exclusive; changed then includes rule_id). SAVE + REBUILD: the mapping is written to the integration and its built feed is rebuilt immediately, but reaching the ad platform still needs a re-export/submit — call repair_ad or submit_all_ad_items afterwards (auto-pilot ads re-export on their next sync). Map only attributes returned by get_ad_attributes; hidden ones are internal and cannot be mapped by regular users. Returns {integrationId, code, status, changed:[...], reason, rebuilt, overridesStepField}; status is 'updated' | 'no_changes' | When the attribute was already driven by a wizard step field, the response says so in overridesStepField: the rewrite rule beats that step for good, so a later change in the step has no effect. If the step already sets the right source, change it there, not here. 'rejected' (reason: unknown_attribute | unknown_source_attribute | value_not_allowed | unknown_rule). Category-specific attributes are mapped here too, the same way — but they only exist after a category is mapped, so run refresh_ad_category_attributes first (they then appear in get_ad_attributes). ad_id is from list_ads. project_id is OPTIONAL (inferred for a single-project customer). OVERWRITES the stored override and detaches a rule attached to that attribute.

Set where one feed attribute's value comes from. Use this to change where a feed column gets its value. Target the output attribute by code (from get_feed). Set platform_code to a source attribute (from list_source_attributes) to map it, and/or constant for a fixed value; default_platform_code / default_constant are the fallback used when the primary source is empty. rule_id attaches a product rule (Attribute Rule, from list_rules / create_rule) — the attribute's value is then computed by that rule; send rule_id:"" to detach it (revert to platform_code/constant), and rule_enabled:false to attach it disabled. To re-enable an attached-but-disabled rule, send rule_enabled:true (with or without its rule_id, from get_feed). rule_enabled on its own applies to whatever rule is already attached; with none attached it is rejected as unknown_rule. Provide at least one field (send an empty string to clear a text field). rule_id together with platform_code/constant in the same call is contradictory and is rejected. Setting a source (platform_code/constant) on an attribute that currently has a rule DETACHES that rule (source and rule are mutually exclusive; changed then includes rule_id). SAVE-ONLY: persists the mapping and bumps the revision but does NOT regenerate the feed — call export_feed afterwards for the change to reach the output. Map only attributes returned by get_feed. Returns {feedId, code, status, changed:[...], reason, revisionBefore, revisionAfter}; status is 'updated' | 'no_changes' | 'rejected' (reason: unknown_attribute | unknown_source_attribute | value_not_allowed | unknown_rule). (rule_id together with platform_code/constant is a request-level invalid_request/400, not a 'rejected' reason.) project_id is OPTIONAL (inferred for a single-project customer). Attributes flagged hidden in get_feed are internal plumbing and cannot be mapped by regular users; skip them. PRECEDENCE: a feed value is resolved rule → composed → platform_code → constant (valueSource 'rule' is a Rule). If an attribute's valueSource (from get_feed) is 'composed', its value comes from a composed rule, so a platform_code/constant you set here is silently overridden — change composed values in the Koongo UI (the feed's editUrl). A 'rule' value source (a Rule), however, is settable here via rule_id. OVERWRITES the stored mapping and detaches a rule attached to that attribute.

Set where ONE of a marketplace's output attributes gets its value — the write half of solving the attribute form. Use this to fill or change one marketplace output attribute. Target the output attribute by code (from get_marketplace_attributes). Set platform_code to a source attribute (from list_source_attributes) to map it, and/or constant for a fixed value; default_platform_code / default_constant are the fallback used when the primary source is empty. For an IDENTIFIER (sku, gtin/ean/barcode, mpn), first confirm the chosen source is actually populated across the catalog (get_project_profile eanFillRate; page preview_products) — mapping or requiring an identifier the products lack yields an empty, non-functional integration. rule_id attaches an Attribute Rule (from list_rules / create_rule) — the value is then computed by that rule; send rule_id:"" to detach it, and rule_enabled:false to attach it disabled. To re-enable an attached-but-disabled rule, send rule_enabled:true (with or without its rule_id, from get_marketplace_attributes). rule_enabled on its own applies to whatever rule is already attached; with none attached it is rejected as unknown_rule. Provide at least one field (send an empty string to clear a text field). rule_id together with platform_code/constant in the same call is contradictory and is rejected. Setting a source (platform_code/constant) on an attribute that currently has a rule DETACHES that rule (mutually exclusive; changed then includes rule_id). SAVE + REBUILD: the mapping is written to the integration and its built feed is rebuilt immediately, but reaching the sales channel still needs a re-export/submit — call repair_marketplace or submit_all_marketplace_items afterwards (auto-pilot marketplaces re-export on their next sync). Map only attributes returned by get_marketplace_attributes; hidden ones are internal and cannot be mapped by regular users. Returns {integrationId, code, status, changed:[...], reason, rebuilt, overridesStepField}; status is 'updated' | 'no_changes' | 'rejected' (reason: unknown_attribute When the attribute was already driven by a wizard step field, the response says so in overridesStepField: the rewrite rule beats that step for good, so a later change in the step has no effect. If the step already sets the right source, change it there, not here. | unknown_source_attribute | value_not_allowed | unknown_rule). Category-specific attributes are mapped here too, the same way — but they only exist after a category is mapped, so run refresh_marketplace_category_attributes first (they then appear in get_marketplace_attributes). marketplace_id is from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer). OVERWRITES the stored override and detaches a rule attached to that attribute.

Get the live run status of one marketplace: readiness, connection, and product/order counts. Use this to check a marketplace's run progress and product counts. Returns {integrationId, status, ready, lastStep, isReady, isConnected, isOverlimit, productsRefreshing, productsSubmitting, productStats:{listed, processing, errors, inactive, total}, orderStats:{total, synced, error, pending}}. productStats counts the listing on the channel; orderStats is present only when order sync is enabled. isOverlimit=true means the product count is above what this Koongo account includes; explain that to the user. productsRefreshing=true means an export / feed generation is running (the integration is 'updating'); productsSubmitting=true means items are being pushed to the channel. While EITHER is true the data is still changing — this is the signal to WAIT: after any export (finishing the wizard summary, repair_marketplace, a step transition that re-exports, or a submit) poll marketplace_status until BOTH productsRefreshing AND productsSubmitting are false, THEN read the results. The KOONGO DATA CHECK (get_marketplace_report's dataCheckErrors) and the productStats counts are only current once the refresh has finished — reading mid-refresh gives stale/empty data. categoryAttributeWarmup is the OTHER wait: on channels whose attributes depend on the mapped categories, that download runs in the background. While the block is present with pending:true the category-driven attributes are NOT in get_marketplace_attributes yet — poll this tool (retryAfterSeconds says how long to wait; state 'rescheduled' means a channel rate limit parked it until nextTryAt) until the block is absent or state is 'ready'. state 'failed' is terminal: call refresh_marketplace_category_attributes ONCE to start it again, do not poll on. marketplace_id is the id from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). Use marketplace_status for run progress and get_marketplace for configuration/mapping. For the detailed error breakdown use get_marketplace_report.

Pause an ad — synchronization to the channel stops until it is resumed with resume_ad. Use this when the user wants an ad to stop syncing. Ads are product-listing channels (Google Shopping, Meta catalog, Microsoft, price comparison) for the merchant's physical products, not marketplaces: they publish products to the channel and have no order sync. Returns {integrationId, action:'pause', status:'paused', kind:'ads'}. ad_id is from list_ads. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

AD items: pause — deactivate the chosen items' offers on the LIVE ad channel without deleting them; a later submit resumes them; pause_ad pauses the whole integration. Use this to hold specific listings. Needs confirm:true after the user agrees. Target item_ids or all_items:true.

Pause (disable) a feed — it stops being exported/submitted on schedule. Use this when the user wants a feed to stop exporting. Returns {feedId, action:'pause', status:'disabled', feedStatus, enabled:false}. feed_id from list_feeds / create_feed; project_id OPTIONAL.

Pause a marketplace — synchronization to the channel stops until it is resumed with resume_marketplace. Use this when the user wants a marketplace to stop syncing. Returns {integrationId, action:'pause', status:'paused', kind}. marketplace_id is from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

MARKETPLACE items: pause — deactivate the chosen items' offers on the LIVE marketplace without deleting them; a later submit resumes them; pause_marketplace pauses the whole integration. Use this to hold specific listings. Needs confirm:true after the user agrees. Target item_ids or all_items:true.

AD-wide pre-pair — pair existing channel listings with the Koongo items; removes and submits nothing. Use this when the channel already holds listings. No confirm needed.

MARKETPLACE-wide pre-pair — pair existing channel listings with the Koongo items; removes and submits nothing. Use this when the channel already holds listings. No confirm needed.

Get a page of the project's imported products with their real source-attribute values, so you can inspect the data and advise on feed mapping (e.g. see that brand holds "Nike" or color holds hex codes). Use this to inspect real product values before mapping. Returns {products:[{id, type, attributes:{:}}], returned, requested, total, offset, hasMore, nextOffset}. attributes keys are source attribute codes (as in list_source_attributes); only catalogued, non-sensitive attributes are included — cost/margin and internal fields are never returned, and empty values are omitted. sample_size is the page window (default 5, max 100); page through the whole catalog with offset — when hasMore is true, re-call with offset=nextOffset until hasMore is false. project_id is OPTIONAL (inferred for a single-project customer). Data must be imported first (see get_import_status). This tool returns real product data values only after you set acknowledge_sensitive:true. The first call (flag absent/false) returns {sensitiveGate:{confirmationRequired:true, itemCount, fields, kind}} with an EMPTY products array — present that gate to the USER, get their approval, then re-call with acknowledge_sensitive:true to receive the actual values. To review the full generated feed output for every product (not just source attributes), use export_feed, not paging this preview — that is the intended bulk path. Pass attributes (source attribute codes) to return only those attributes, with values up to 20000 chars (otherwise 200); the response then also carries attributes, valueMaxLength and withheldAttributes. With attributes, sample_size x the number of attributes may be at most 100 (default sample_size 5 counts too), so long values cannot flood the conversation; to show a merchant full values keep sample_size <= 10. Next: pick a template (list_feed_templates) and map attributes (map_feed_attribute).

AD category attributes — fetch the channel's CATEGORY attributes for the ad's currently mapped categories and refresh its rewrite rules — the same 'Update Category Attributes' action the wizard runs. Use this to load an ad's category attributes after mapping categories. Some ad channels expose extra, category-specific required attributes that only appear AFTER a category is mapped; run this after configuring the category-mapping step so those attributes show up in get_ad_attributes. Calls the channel (a live read) and rebuilds the integration. After this the category attributes appear in get_ad_attributes and you map them with map_ad_attribute like any other attribute. Returns {integrationId, action:'refresh_category_attributes', status:'updated', kind, editUrl, message}. Re-export/submit afterwards to reach the channel. ad_id is from list_ads. project_id is OPTIONAL (project_id_required otherwise — then call list_projects). ON CHANNELS THAT PRE-CACHE, THIS DOES NOT CALL THE CHANNEL SYNCHRONOUSLY: if the attributes for the current categories are not downloaded yet it returns status:'warming' with a categoryAttributeWarmup block and does the work in the background — that is a SUCCESS, not an error. Then poll ad_status until the block is absent or state is 'ready'; the attributes are pulled in automatically, so you do NOT have to call this again. Only call it a second time if ad_status reports state 'failed'.

MARKETPLACE category attributes — fetch the channel's CATEGORY attributes for the marketplace's currently mapped categories and refresh its rewrite rules — the same 'Update Category Attributes' action the wizard runs. Use this to load category-specific attributes after mapping categories. Many channels expose extra, category-specific required attributes (e.g. Amazon per product type) that only appear AFTER a category is mapped; run this after configuring the category-mapping step so those attributes show up in get_marketplace_attributes. Calls the channel (a live read) and rebuilds the integration. After this the category attributes appear in get_marketplace_attributes and you map them with map_marketplace_attribute like any other attribute. Returns {integrationId, action:'refresh_category_attributes', status:'updated', kind, editUrl, message}. Re-export/submit afterwards to reach the channel. marketplace_id is from list_marketplaces. project_id is OPTIONAL (project_id_required otherwise — then call list_projects). ON CHANNELS THAT PRE-CACHE, THIS DOES NOT CALL THE CHANNEL SYNCHRONOUSLY: if the attributes for the current categories are not downloaded yet it returns status:'warming' with a categoryAttributeWarmup block and does the work in the background — that is a SUCCESS, not an error. Then poll marketplace_status until the block is absent or state is 'ready'; the attributes are pulled in automatically, so you do NOT have to call this again. Only call it a second time if marketplace_status reports state 'failed'.

AD items: remove — end the chosen items' listings on the LIVE ad channel; a later submit creates a new listing. Use this when the user asks to take specific listings down. Needs confirm:true after the user agrees. Target item_ids or all_items:true.

AD-wide remove all — remove EVERY item from the LIVE ad channel and lock them; PERMANENT. Use this when the user asks to take all listings down. Needs confirm:true after the user agrees.

MARKETPLACE-wide remove all — remove EVERY item from the LIVE marketplace and lock them; PERMANENT. Use this when the user asks to take all listings down. Needs confirm:true after the user agrees.

MARKETPLACE items: remove — end the chosen items' listings on the LIVE marketplace; a later submit creates a new listing. Use this when the user asks to take specific listings down. Needs confirm:true after the user agrees. Target item_ids or all_items:true.

Repair an ad — rebuild its internal profiles, clear its cache and re-export. Ads are product-listing channels (Google Shopping, Meta catalog, Microsoft, price comparison) for the merchant's physical products, not marketplaces: they publish products to the channel and have no order sync. Use this when an ad is in a broken or inconsistent state. Returns {integrationId, action:'repair', status:'repaired', kind:'ads', message}. ad_id is from list_ads. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). Re-export replaces generated output and can publish through an active automatic integration. Confirm with the user before repair; do not retry blindly.

Repair a marketplace — rebuild its internal profiles, clear its cache and re-export. Use this when a marketplace is in a broken or inconsistent state. Returns {integrationId, action:'repair', status:'repaired', kind, message}. marketplace_id is from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). Re-export replaces generated output and can publish through an active automatic integration. Confirm with the user before repair; do not retry blindly.

Report a problem, gap, or workaround with THIS MCP toolset back to the Koongo team so it can be fixed or extended. Use this to report a tool error or a missing capability to Koongo. Use it when: a tool returned an error you could not resolve after a legitimate attempt (ESPECIALLY a 500 / unexpected server error or an unreachable-facade error), a capability you needed is missing, a tool's result was wrong or confusing versus what its docs implied, or you and the user AGREED on a manual workaround because MCP could not do something — or whenever the user says 'report this'. This is BACKGROUND product feedback, not a user-facing action and not something the user's task depends on: briefly ask the user's OK first ('want me to report this?'), file ONE report per scenario, then continue — do NOT loop or re-file the same thing. Provide category + a short title + a detailed description (what the user wanted, what actually happened, and any agreement/workaround). Strongly include steps[] — the CALL STACK: the sequence of tools you called with their key arguments and each one's outcome/error — plus the specific error, and expected vs actual where relevant, so an engineer can reproduce from the report alone. Never put credentials, tokens, API keys or personal data in a report (the server redacts known-sensitive keys defensively, but you must not include them). Returns {status:'recorded', reportId, ts}.

Restore a soft-deleted feed and re-export it. Use this when a feed was deleted (delete_feed) — get_feed (and other feed actions) report a deleted feed as error 'feed_deleted', which is recoverable; list_feeds simply omits it while deleted — or when the user asks to bring a feed back. The feed id stays valid after deletion; this reverses it. Returns {feedId, action:'restore', status:'restored'}. feed_id from the feed_deleted error or an earlier list_feeds; project_id OPTIONAL. Restoration queues a fresh export on every call and may resume external publishing when the feed is enabled. Confirm with the user; do not retry blindly.

Resume a paused ad — synchronization to the channel starts again. Use this when the user wants a paused ad to sync again. Ads are product-listing channels (Google Shopping, Meta catalog, Microsoft, price comparison) for the merchant's physical products, not marketplaces: they publish products to the channel and have no order sync. Returns {integrationId, action:'resume', status:'resumed', kind:'ads'}. ad_id is from list_ads. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). Resuming can restart automatic publication to the live ad channel. Confirm with the user before resuming.

Resume (re-enable) a paused feed. Returns {feedId, action:'resume', status:'enabled', feedStatus, enabled:true}. Use this when the user wants a paused feed to export again. feed_id from list_feeds / create_feed; project_id OPTIONAL. Re-enabling permits scheduled export and submission to resume, including changes to live listings. Confirm with the user before enabling.

Resume a paused marketplace — synchronization to the channel starts again. Use this when the user wants a paused marketplace to sync again. Returns {integrationId, action:'resume', status:'resumed', kind}. marketplace_id is from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). Resuming can restart automatic publication to the live marketplace. Confirm with the user before resuming.

Apply stored additional-source (AI) values onto products (they land as custom_). Use this to apply them after the last set_ai_source batch, after delete_ai_source, or to retry a failed import. Overwrites the products' existing custom_ values. Also downloads the additional-source URLs already configured on this project; takes no URL. Returns {status:'dispatched'|'skipped', type}; 'skipped' = store data not connected. ASYNC: poll get_import_status until the newest additional_source run has running:false and status 'ok'. 'addon_required' (HTTP 403) = not included in this Koongo account; do not retry. project_id OPTIONAL.

Apply stored API-source values onto products (they land as api_source.). Use this to apply them after the last set_api_source batch, after delete_api_source, or to retry a failed import. Replaces each product's api_source values with the stored ones (values no longer stored are dropped); fetches nothing from outside Koongo. Returns {status:'dispatched'|'skipped', type}; 'skipped' = store data not connected. ASYNC: poll get_import_status until the newest api_source run has running:false and status 'ok'. 'addon_required' (HTTP 403) = not included in this Koongo account; do not retry. project_id OPTIONAL.

Search a feed's target taxonomy tree (marketplace categories) by a substring of the category path. Use this to find the target category id for a mapping. Address the taxonomy by feed_id (its taxonomy is used) OR explicitly by taxonomy_code (+ optional taxonomy_locale). Returns {categories:[{hash, name, path}], returned, total, taxonomyCode, taxonomyLocale}; pass a returned hash as target_hash to set_category_mapping. query matches the full path (e.g. 'laptop', 'shoes'); limit bounds the results (default 50). project_id is OPTIONAL (inferred for a single-project customer).

Switch an ad to AUTOMATIC product mode: every matching product is published to the LIVE ad channel and kept in sync, and a submission is queued right away. Use this when the user wants ongoing automatic publishing. Each call queues the submission again, even when already automatic — do not retry blindly. Returns {integrationId, action:'set_product_mode', status, kind:'ads', editUrl, message}. Needs confirm:true after the user agrees. ad_id is from list_ads. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Switch an ad to MANUAL product mode: nothing is published automatically; items reach the channel only through submit_ad_items / submit_all_ad_items. Use this to test before activating or to stop automatic publishing. Sends nothing to the channel; to stop all syncing use pause_ad. Returns {integrationId, action:'set_product_mode', status, kind:'ads', editUrl, message}. ad_id is from list_ads. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

AD name — set or clear the human-readable name of an ad so you (and the user) can identify it later. Names are free-text and NOT unique — use this to give an unnamed ad a memorable label, or to rename one. Pass name:"" (empty) to clear the name back to none. Returns {integrationId, action:'set_name', status:'updated', kind, editUrl, message}. ad_id is from list_ads. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

AI SOURCE (CSV-joined enrichment) — store per-product values that YOU (the client's own model) extracted, as a new 'AI source' attribute — so a feed rule can read the attribute directly without matching free text with contains/conditions. Use this to store values your own model extracted per product. Typical flow: call preview_products to read products, derive ONE value per product with your own reasoning (e.g. the color, gender, or material from the title/description), then call this with values as a JSON OBJECT (not an array) mapping each product's id (the id field from preview_products) to the extracted value. code is the new attribute name (e.g. "ai_color"); once applied it becomes the source attribute custom_ (visible in list_source_attributes). Send large catalogs in BATCHES: first batch mode:"replace", following batches mode:"append". This only STORES the values; after the LAST batch call run_ai_source_import so they land on products (an ASYNCHRONOUS import). VERIFY before using it: poll get_import_status until the newest additional_source run in recentRuns has running:false and status 'ok', and the code appears in list_source_attributes; only THEN attach the attribute to a feed with map_feed_attribute. If that run errors, run_ai_source_import retries without re-sending the values. handle overrides the product key to join on (default header.id, which matches the preview_products id). project_id is OPTIONAL (inferred for a single-project customer). If this feature is not included in this Koongo account, the call is refused with error 'addon_required' (HTTP 403); tell the user it is not available for this account and do not retry. Returns {status:'written', code, url, valueCount, applied:false}. The default mode replace OVERWRITES every stored value of the source.

API SOURCE (written to the data store) — store per-product values that YOU (the client's own model) computed, as a new 'API source' attribute — written straight into the project's data store (no CSV, no join handle) — so a feed rule can read the attribute directly without matching free text with contains/conditions. Use this to store values computed per product as a new attribute. It fits whenever a rule would otherwise need a long or complex condition tree. Typical flow: call preview_products to read products, derive ONE value per product with your own reasoning (e.g. the color, gender, or material from the title/description), then call this with values as a JSON OBJECT (not an array) mapping each product's id (the id field from preview_products) to the computed value. Values keep their JSON type — send a NUMBER for a numeric attribute (so numeric rule operators work), a boolean, or a string; a null clears that product. code is the new attribute name (e.g. "ai_color"); once applied it becomes the source attribute api_source. (visible in list_source_attributes). Send large catalogs in BATCHES: first batch mode:"replace", following batches mode:"append". This only STORES the values; after the LAST batch call run_api_source_import so they land on products (an ASYNCHRONOUS import). VERIFY before using it: poll get_import_status until the newest api_source run in recentRuns has running:false and status 'ok', and the code appears in list_source_attributes; only THEN attach the attribute to a feed with map_feed_attribute or reference api_source. in a rule (create_rule / update_rule). If that run errors, run_api_source_import retries without re-sending the values. code must not collide with an existing source attribute of another class. project_id is OPTIONAL (inferred for a single-project customer). If this feature is not included in this Koongo account, the call is refused with error 'addon_required' (HTTP 403); tell the user it is not available for this account and do not retry. Returns {status:'written', code, valueCount, applied:false}. mode=replace clears the attribute on every product; a null value clears it on one.

Map store categories to marketplace/taxonomy categories. Use this to save store-to-target category mappings. Address the taxonomy by feed_id OR explicitly by taxonomy_code (+ optional taxonomy_locale). rules is a list of {store_category_ids:[...], target_hash} — each maps those store categories (ids from list_store_categories / list_unmapped_categories) to one target (hash from search_target_categories); a store category already mapped is re-pointed to the new target. The rule set is SHARED per project+taxonomy+locale, so if OTHER feeds use this taxonomy the call returns status=mapping_exists_requires_confirm (HTTP 409) with affectedFeedIds — re-call with confirm:true to apply. SAVE-ONLY: persists but does NOT regenerate — call export_feed afterwards. Returns {taxonomyCode, taxonomyLocale, status, rulesWritten, reason, affectedFeedIds}; status is 'updated' | 'no_changes' | 'mapping_exists_requires_confirm' | 'rejected' (reason: no_taxonomy | unknown_target | unknown_store_category | empty_rules). project_id is OPTIONAL (inferred for a single-project customer).

Set (or clear) a feed's ATTRIBUTE filter: conditions on source attributes that decide which products export, joined by combination 'and' | 'or' (default 'and'). Use this to filter feed products by attribute conditions. Each condition is {attribute, operator, value}: attribute is a source attribute code (from list_source_attributes); operator is one of equals, not_equals, contains, not_contains, starts, not_starts, ends, not_ends, empty, not_empty, greater, greater_or_equal, less, less_or_equal, regex, not_regex, is_true, is_false; value is the comparison string (omit for empty / not_empty). Pass conditions:[] to CLEAR the attribute filter. This is separate from the category filter (set_feed_filter). To include or exclude out-of-stock products use export_out_of_stock on set_feed_filter — never build a qty/stock condition here. SAVE-ONLY: persists and bumps the revision but does NOT regenerate — call export_feed afterwards. Returns {feedId, status, changed, reason, revisionBefore, revisionAfter}; status is 'updated' | 'no_changes' | 'rejected' (reason: invalid_value | unknown_source_attribute | invalid_condition). project_id is OPTIONAL (inferred for a single-project customer). REPLACES the whole attribute filter, nested groups included.

Set a feed's product filter — which products reach the output. Use this to choose which products a feed exports. Common flags: export_out_of_stock (include items with zero stock), export_variants_as_single (export child variants, not the parent), export_removed_products (no = only active | yes = all incl. removed | only = removed only). Category filter: category_ids (store category ids from list_store_categories) with category_operator include|exclude (default include); category_ids:[] clears the category filter (export all categories). Provide at least one field; a field you omit is left unchanged. SAVE-ONLY: persists and bumps the revision but does NOT regenerate the feed — call export_feed afterwards. Returns {feedId, status, changed:[...], reason, revisionBefore, revisionAfter}; status is 'updated' | 'no_changes' | 'rejected' (reason: invalid_value | unknown_store_category). project_id is OPTIONAL (inferred for a single-project customer). OVERWRITES the flags given and replaces category_ids as a whole.

Rename a feed. Use this when the user wants a feed to have a different name. Only the name changes (pause_feed / resume_feed handle enabling). Returns {feedId, status:'updated'|'no_changes', changed, name, enabled, revisionBefore, revisionAfter}; the previous name is not returned. feed_id from list_feeds / create_feed; project_id OPTIONAL.

Set a feed's general output settings: SHIPPING cost and STOCK. Use this to change a feed's stock and shipping output settings. Send shipping and/or stock; within each object only the keys you include change (omitted keys are left as-is). shipping: {dependent_attribute (a source attribute code from list_source_attributes the cost depends on, e.g. weight/price — '' clears it), method_name (free text), intervals (the cost table — REPLACES the whole set; each row {from, to, cost} numeric with 0 <= from <= to <= 1000000 and cost >= 0; intervals:[] clears all rows)}. stock: {in_value (the value exported when a product is In stock), out_value (the value when Out of stock), availability_attribute (a source attribute code exported as availability when out of stock — '' clears it)}. Provide at least one of shipping / stock. To rename the feed use set_feed_name (the feed name is not set here). SAVE-ONLY: persists and bumps the revision but does NOT regenerate the feed — call export_feed afterwards. Read the current values from get_feed (settings). Returns {feedId, status, changed:[...], reason, revisionBefore, revisionAfter}; status is 'updated' | 'no_changes' | 'rejected' (reason: invalid_value | unknown_source_attribute | invalid_interval). project_id is OPTIONAL (inferred for a single-project customer). OVERWRITES the keys given; shipping.intervals replaces the whole table.

Switch a marketplace to AUTOMATIC product mode: every matching product is published to the LIVE marketplace and kept in sync, and a submission is queued right away. Use this when the user wants ongoing automatic publishing. Each call queues the submission again, even when already automatic — do not retry blindly. Returns {integrationId, action:'set_product_mode', status, kind, editUrl, message}. Needs confirm:true after the user agrees. marketplace_id is from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Switch a marketplace to MANUAL product mode: nothing is published automatically; items reach the channel only through submit_marketplace_items / submit_all_marketplace_items. Use this to test before activating or to stop automatic publishing. Sends nothing to the channel; to stop all syncing use pause_marketplace. Returns {integrationId, action:'set_product_mode', status, kind, editUrl, message}. marketplace_id is from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

MARKETPLACE name — set or clear the human-readable name of a marketplace so you (and the user) can identify it later. Names are free-text and NOT unique — use this to give an unnamed marketplace a memorable label, or to rename one. Pass name:"" (empty) to clear the name back to none. Returns {integrationId, action:'set_name', status:'updated', kind, editUrl, message}. marketplace_id is from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Start importing a marketplace's orders: Koongo registers order webhooks with the marketplace. Use this when the user wants a marketplace's orders to flow into the shop. Needs order sync on the marketplace: otherwise 'prerequisite_not_met' (HTTP 409) — call enable_marketplace_order_sync and configure its order-settings step first. 'rejected' when order sync is not included in this Koongo account. Returns {integrationId, action:'set_order_mode', status, kind, editUrl, message}. Undo with stop_marketplace_order_sync. marketplace_id is from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

Stop importing a marketplace's orders: Koongo unregisters its order webhooks with the marketplace. Use this when the user wants a marketplace's orders to stop flowing into the shop. Imported orders and product listings stay. Returns {integrationId, action:'set_order_mode', status, kind, editUrl, message}. Undo with start_marketplace_order_sync. marketplace_id is from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).

AD items: submit — send the chosen items to the LIVE ad channel, also in MANUAL product mode (one item_id is the safe test). Use this when the user asks to publish specific listings. Needs confirm:true after the user agrees. Target item_ids or all_items:true.

AD-wide submit all — submit EVERY item to the LIVE ad channel; MANUAL product mode only (else status:'not_allowed'). Use this when the user asks to publish all listings. Needs confirm:true after the user agrees.

MARKETPLACE-wide submit all — submit EVERY item to the LIVE marketplace; MANUAL product mode only (else status:'not_allowed'). Use this when the user asks to publish all listings. Needs confirm:true after the user agrees.

Submit a generated feed to its sales channel (only meaningful for API channels with a connection; file feeds that the channel pulls are not submitted). Use this to send a generated feed to its connected channel. The feed must be generated first (status='generated' from get_feed_status) — otherwise returns error 'feed_not_generated'. Returns {feedId, action:'submit', status, feedStatus, message}. status is 'submitted' (ok), 'not_submittable' (channel doesn't accept submissions), or 'failed' (with message). feed_id from list_feeds / create_feed; project_id OPTIONAL. Run verify_feed_attributes before submitting. This sends product data to the live channel and can replace existing listings. Confirm the submission with the user; a later submission does not undo the original channel effects.

MARKETPLACE items: submit — send the chosen items to the LIVE marketplace, also in MANUAL product mode (one item_id is the safe test). Use this when the user asks to publish specific listings. Needs confirm:true after the user agrees. Target item_ids or all_items:true.

Pull orders from the channel NOW — a manual, one-off order import (in addition to the automatic sync that runs on its own when order sync is enabled). Use this when the user wants a marketplace's orders imported right now. The import runs asynchronously; watch the counts in marketplace_status.orderStats. Requires the marketplace's connection to be active for orders — otherwise returns status 'prerequisite_not_met' (HTTP 409). Returns {integrationId, action:'sync_orders', status, kind, editUrl, message}; status is 'updated' when the import was started. marketplace_id is from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). Marketplaces only — ads have no order sync.

Start an order synchronization for the whole project now — ONE background process that pulls orders across ALL of the project's order connections at once (the same run as the Koongo 'Sync Now' button; it also overlaps with any marketplace order sync, since order sync runs once per project). Use this when the user wants all order connections synced now. Returns {action:'sync', status:'done', message}; if a sync is already running that run continues (status stays 'done'). This is heavy and project-wide: to check a SINGLE connection use test_order_connection instead. Order counts then move in get_order_overview. project_id is OPTIONAL (project_id_required otherwise — then call list_projects).

Verify that an ad integration's saved connection still works — runs a live connectivity/auth check against the ad channel right now. Each ad owns exactly ONE connection (never shared), so no separate handle is needed: the ad_id IS the connection. Use this when an ad looks connected but items fail, or after credentials/OAuth may have expired. Returns {integrationId, status ('ok' | 'error' | 'not_connected'), message}. 'not_connected' means the connection step was never completed; to move a connection to a different channel there is no transfer — clone the ad with clone_ad. Never returns secrets. This does not change any settings. Fixing or (re)establishing a connection (credentials / OAuth) is done by the USER in the browser / Koongo UI, never via MCP: on 'error' / 'not_connected' route the user there, do not retry configure_ad_step to set credentials. ad_id is from list_ads. project_id is OPTIONAL (project_id_required otherwise — then call list_projects).

Verify that a marketplace's saved connection still works — runs a live connectivity/auth check against the channel right now. Each marketplace owns exactly ONE connection (never shared), so no separate handle is needed: the marketplace_id IS the connection. Use this when a marketplace looks connected but items fail, or after credentials/OAuth may have expired. Returns {integrationId, status ('ok' | 'error' | 'not_connected'), message}. 'not_connected' means the connection step was never completed; to move a connection to a different channel there is no transfer — clone the marketplace with clone_marketplace. Never returns secrets. This does not change any settings. Fixing or (re)establishing a connection (credentials / OAuth) is done by the USER in the browser / Koongo UI, never via MCP: on 'error' / 'not_connected' route the user there, do not retry configure_marketplace_step to set credentials. marketplace_id is from list_marketplaces. project_id is OPTIONAL (project_id_required otherwise — then call list_projects).

Verify that a standalone order connection's saved credentials still work — a live connectivity/auth check right now. Returns {connectionId, status ('ok'|'error'|'not_connected'), message} — the message is masked and never contains secrets. 'not_connected' means authentication was never completed: route the USER to finish it in the Koongo UI (never via MCP), do not try to set credentials. Use this to confirm a connection is healthy before enabling it with activate_order_connection. This is the right way to check a SINGLE connection — do not run sync_project_orders for that. connection_id is from get_order_overview. project_id is OPTIONAL (project_id_required otherwise — then call list_projects).

AD items: release lock — clear the lock set by lock_ad_items so automatic sync updates the items again. Use this when frozen listings should sync again. Needs confirm:true after the user agrees. Target item_ids or all_items:true.

MARKETPLACE items: release lock — clear the lock set by lock_marketplace_items so automatic sync updates the items again. Use this when frozen listings should sync again. Needs confirm:true after the user agrees. Target item_ids or all_items:true.

Update an EXISTING product rule (Attribute Rule). Use this to change a saved rule after validate_rule passes. Always validate_rule the new document first and fix every error. Identify the rule by rule_id (from list_rules / get_rule) and pass the full rule document as rule — {name, description, category, icon, rules:[{sortId, enabled, type, conditions, operationGroups: [{mode, parentMode, attributes, operations:[{name, arguments:{key:value}}]}]}]}. The safe pattern is: get_rule, edit the returned document, validate_rule, then update_rule with it. Only name, description, category, icon and rules are editable; usage/bookkeeping fields are preserved server-side. A get_rule document already carries map_attribute_value search/replace in the correct {value:''}-objects form (paired by index) — edit those entries verbatim, never flatten them to plain strings (plain strings save but map nothing). update_rule keeps ruleId + every attachment, so the edit updates all attributes using this rule; the value/options mapping is not run by validate_rule's dry-run — verify after a real export/build. scope selects the library: 'project' (default) or 'shared_template' (a template_read_only error means your access cannot write there). Returns {ruleId, scope, status, changed, reason, validation}; status 'updated' / 'no_changes' on success, or 'rejected' with the validation errors when invalid (HTTP 200, nothing written). SAVE-ONLY: this stores the document and runs none of its transform steps; the edit reaches a feed's output only after export_feed on the feeds that use this rule. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). OVERWRITES the pipeline in every feed that uses the rule.

Validate a product rule (Attribute Rule) WITHOUT saving it. Use this to check a rule before create_rule / update_rule and fix every error first. Pass the full rule document as rule — {name, description, category, icon, rules:[{sortId, enabled, type, conditions, operationGroups:[{mode, parentMode, attributes, operations: [{name, arguments:{key:value}}]}]}]} (see list_rule_transforms for the transform-step/condition/argument vocabulary). Returns {valid, errors:[{path, code, message}], warnings:[{path, code, message}], dryRun}. Errors are blocking — the rule will be rejected on save; warnings are advisory. If you also pass a sample_product (a flat {attributeCode:value} record, e.g. from preview_products) and the rule is structurally valid, the server dry-runs it and returns dryRun:{matchedRuleSortId, computedValue, usedAttributes} so you can confirm the output before saving. This tool never writes. project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects). The dry-run runs in memory and calls nothing outside Koongo. When you do NOT pass sample_product, the server auto-samples a real product to compute dryRun, so the computedValue is real data returned only after you set acknowledge_sensitive:true: the first such call (flag absent/false) returns {sensitiveGate:{confirmationRequired:true, itemCount, fields, kind}} with the computedValue EMPTY — present that gate to the USER, get their approval, then re-call with acknowledge_sensitive:true. (If you passed your own sample_product you already hold that data, so no gate applies and the computedValue is returned directly.) DRY-RUN LIMITATION: AI-group transform steps — notably map_attribute_value (value/options mapping) — are NOT executed by the dry-run. It returns valid:true with computedValue = the input UNCHANGED (passthrough) even when the mapping is correct; this is expected, not a bug, so do NOT treat the unchanged value as a failure. Verify a value/options mapping only AFTER a real build/export: feed → export_feed then verify_feed_attributes; marketplace/ad → repair_marketplace / submit_all_marketplace_items (or the ad equivalents) then get_*_report.

File-level check of a feed's attribute mapping (reads the generated feed file). Use this to check the exported attribute values after export_feed. Inputs: feed_id (the feed's id from list_feeds / create_feed), project_id (OPTIONAL — inferred for a single-project customer; project_id_required if they have several, then call list_projects), sample_size (default 20, max 20), offset (default 0 — skip this many items to verify a deeper page of the feed; page by increasing offset in steps of sample_size). Returns deterministic findings against the generated feed file: missingSource (required attributes with no source in the config), emptyInOutput (required attributes empty in the sampled items), specViolations (values outside the channel's allowed set), plus the feed spec (required + allowedValues per attribute) and a sample of items {field: value}. After reading the deterministic findings, YOU do the semantic pass: over sample vs spec, judge whether open-ended values (titles, descriptions, urls, prices, categories) look correct/plausible for the channel, then summarise the problems and suggest concrete config fixes in the feed. status is ok | issues_found | file_missing (file_missing = the feed hasn't been generated yet). The sampled feed rows and violation values are real data returned only after you set acknowledge_sensitive:true. The first call (flag absent/false) returns {sensitiveGate:{confirmationRequired:true, itemCount, fields, kind}} with the sample rows / violation values EMPTY — present that gate to the USER, get their approval, then re-call with acknowledge_sensitive:true to receive the actual values. To fix findings: map_feed_attribute for each, then export_feed, then re-run this tool.