configure_ad_step
Configure ONE step of an ad's setup wizard. CRITICAL: configuring the SUMMARY step FINISHES + ACTIVATES the ad — in AUTO product mode that publishes EVERY matching product to the LIVE channel (spends budget), so to test safely set MANUAL mode FIRST (set_ad_product_mode) and submit one item with run_ad_item_action; check activationBehavior in get_ad before finishing. Ads are ads-based channels (advertising / price-comparison / classifieds), not marketplaces, and have no order sync. Ads are set up step by step IN ORDER: call this repeatedly, targeting each step the previous result reported as nextStepType, until nextStepType is null (setup complete). Identify the step by step_index (from get_ad steps[].index) — REQUIRED to disambiguate when two steps share a step_type (e.g. two 'form' steps); step_type alone targets the FIRST step of that type. Configuring out of order or before prerequisites are met returns 'prerequisite_not_met' / 'step_not_available' (e.g. category mapping precedes the attribute step). PAYLOAD: for a form / order-settings step, payload = {items: {fieldCode: value, ...}} built from that step's fields (get_ad steps[].fields — each field is {code, label, type, required, options, optionsSource, htmlAttributes, value, help}); send ONLY the fields you want to change — the others keep their current value and nothing is deleted. A dropdown/options field takes the option's VALUE — options is a list of {value, label} rows, so send options[].value, NEVER a row's position in that list; read steps[].fields[].options first. Structured steps use their own payload: the product-filter step accepts attribute_filter (the condition tree as a JSON string, or "" to clear it), category_filter (a JSON string {categories_operator, categories:[...]}), and the flag export_out_of_stock ("0"|"1"); send ONLY what changes — it merges over the current filter, so the untouched flags/filters are kept. To include or exclude out-of-stock products use the export_out_of_stock flag — NEVER put a qty/stock condition in attribute_filter (it is an invalid state and is rejected). (export_children_as_parent and export_removed_products are managed in the Koongo UI and CANNOT be set here — sending either is rejected.) category-mapping and mapping-table likewise take their own payload. Returns {integrationId, stepType, status, ready, lastStep, nextStepType, oauthUrl, transitions[], message}. When transitions[] reports a product export/generation (e.g. moving into the summary/preview), that runs ASYNC — poll ad_status until productsRefreshing AND productsSubmitting are false before reading get_ad_report (its dataCheckErrors = the KOONGO DATA CHECK) or trusting counts. status: 'saved' (applied; transitions[] lists automation that ran), 'oauth_required' or 'credentials_in_ui' (a CONNECTION step — see below; TERMINAL, do not retry), 'prerequisite_not_met' / 'step_not_available', or 'validation_failed' (the message lists the field problems — unknown field, value outside its options, non-numeric value, or missing required field — fix them using the step's fields). CONNECTION IS NOT CONFIGURABLE HERE: the connection/auth step (credentials, API keys, OAuth, auth settings) can NEVER be set through MCP — this is intentional and permanent for security, not a limitation to work around. When a step returns 'oauth_required' or 'credentials_in_ui', that status is FINAL for that step: do NOT resend it, do NOT guess field codes or a payload, do NOT keep retrying — the result will not change (it is not transient and not a validation error you can fix). Hand the returned oauthUrl (OAuth) or editUrl (credentials, entered in the Koongo UI) to the USER, then STOP and wait; once they finish, re-check ad_status (isConnected) and continue with the NEXT step. 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).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ad_id | Yes | ||
| payload | No | Settings for this step. Form / order-settings: {items: {fieldCode: value}} from get_ad steps[].fields. A connection/auth step takes NO payload and cannot be configured here — omit it (also for advance-only steps). | |
| step_type | No | Target the step by type (the nextStepType from the previous step). Ambiguous when two steps share a type — prefer step_index. | |
| project_id | No | ||
| step_index | No | Target the step by its index (get_ad steps[].index) — use this to disambiguate steps that share a step_type. |