Vendooly

READ-ONLY. Tutti gli ASIN del catalogo e delle vendite recenti di un outpost, uno per uno, con SKU, titolo, stock, vendite e copertura Sponsored Products LIVE. Incrocia tutte le Product Ads e gli stati campagna/gruppo. Nessun campionamento; dati incompleti o obsoleti producono errore, mai falsi scoperti. Per prodotti venduti senza SP attive usare only_with_sales=true e only_uncovered=true. Richiede data-hub sincronizzato e Ads collegate.

Create an Amazon Ads portfolio to group campaigns (no portfolio-level budget cap; campaigns can then be assigned to it). Same scope as campaigns — no extra authorization needed.

Create a SP ad group in an existing campaign. Defaults to PAUSED so it can be populated before delivery. IMPORTANTE — un ad group è O keyword-targeted O product-targeted, MAI entrambi: Amazon RIFIUTA (otherError) una keyword in un ad group che ha già product target, e viceversa. Quindi se ti servono SIA keyword SIA target di prodotto, crea DUE ad group separati nella stessa campagna: uno popolato con ads_create_sp_keywords, l'altro con ads_create_sp_product_targets. Le NEGATIVE keyword/target invece convivono con qualsiasi tipo.

Create a SP campaign. campaign.targeting_type: "AUTO" (Amazon sceglie automaticamente i target — NON aggiungere keyword/target manuali; per modulare i bid dei 4 gruppi auto usa ads_create_sp_product_targets con auto_match) oppure "MANUAL" (default; poi attacchi keyword via ads_create_sp_keywords o ASIN via ads_create_sp_product_targets). Placement bidding: passa placement_bidding [{placement, percentage}] con placement PLACEMENT_TOP|PLACEMENT_PRODUCT_PAGE|PLACEMENT_REST_OF_SEARCH|SITE_AMAZON_BUSINESS (0-900%). Strategy via dynamic_bidding.strategy (LEGACY_FOR_SALES|AUTO_FOR_SALES|MANUAL|RULE_BASED). Optionally assign to a portfolio via portfolio_id.

Create SP keywords. L'ad group bersaglio deve essere keyword-targeted: se ha GIÀ product target Amazon rifiuta con otherError (un ad group è keyword O product, mai entrambi) → in quel caso crea un ad group dedicato alle keyword. Ogni keyword: { campaign_id, ad_group_id, keyword_text, match_type (BROAD|PHRASE|EXACT), bid }.

Create SP negative keywords

Create SP negative product targets. Each: { campaign_id, ad_group_id, asin (or raw expression) }.

Create SP product ads

Create SP targets. MANUAL (campagne MANUAL): ogni target { campaign_id, ad_group_id, bid, e uno tra: asin (ASIN target), category_id (category target), expression (raw v3) }. AUTO (campagne AUTO): per impostare il bid sui 4 gruppi di matching automatico usa { campaign_id, ad_group_id, bid, auto_match: "close"|"loose"|"substitutes"|"complements" } (close=ricerche strettamente correlate, loose=genericamente correlate, substitutes=prodotti alternativi, complements=accessori). ATTENZIONE: su una campagna AUTO GIÀ ESISTENTE i 4 gruppi sono già stati creati da Amazon — ri-crearli qui dà errore INVALID_ARGUMENT. Per cambiarne solo il bid NON usare questo tool: usa ads_list_sp_targets per leggere il targetId del gruppo e poi ads_update_sp_target_bid.

Archivia (elimina) una o più campagne SP. È l'UNICO modo di archiviare una campagna: ads_update_sp_campaign accetta solo ENABLED|PAUSED (Amazon rifiuta ARCHIVED sul PUT). IRREVERSIBILE — una campagna archiviata non si riattiva, va ricreata. campaign_ids: [id, ...].

Delete SP negative keywords

Delete (archive) SP negative product targets

Delete (archive) SP product targets

READ-ONLY, LIVE. Quanto del budget GIORNALIERO ogni campagna ha già consumato OGGI, in percentuale (dato INTRAGIORNALIERO, aggiornato da Amazon ogni ~10-15 min). Serve alla domanda "quali campagne stanno per restare senza budget adesso / sono già andate dark?": a 100% la campagna esce dall'asta fino a mezzanotte. È l'UNICA fonte del dato di oggi — il data-hub (fact_campaign_daily) è giornaliero e al massimo dice che IERI una campagna ha saturato. Per storico, ACoS, spesa e trend usa execute_sql, NON questo tool. Senza campaign_ids controlla tutte le campagne ENABLED dell'ad product. ad_product: SP (default) | SB | SD.

List Amazon Ads portfolios (groups of campaigns with optional shared budget)

List Amazon Ads profiles for this account

Read-only: elenco ad group Sponsored Brands (SB) — id, nome, stato (ENABLED|PAUSED|ARCHIVED), campagna di appartenenza. Filtra con campaign_id_filter.

LIVE: stato corrente delle campagne Sponsored Brands (SB) ESISTENTI (create da Amazon Ads console — Vendooly non crea ancora campagne SB nuove, serve brandEntityId/Brand Registry/asset creativi/moderazione, non implementato). Campi chiave: name, campaignId, state (ENABLED|PAUSED|ARCHIVED), daily_budget, costType (CPC|vCPM), bidding (placement/bidOptimization), brandEntityId. NON ritorna performance: per ACoS/spesa/vendite SB usa execute_sql su fact_campaign_daily (ad_product='SB').

LIVE: keyword Sponsored Brands (SB) con BID e stato ATTUALI — la lettura da fare prima di riofferire su SB. Filtra con campaign_id/ad_group_id. NON ritorna performance: per spesa/vendite/ACoS usa execute_sql su fact_keyword_daily. Elenco vuoto = quel brand non ha keyword SB (tipico se le campagne SB usano product targeting o non esistono): dillo, NON inventare keyword.

LIVE: product target Sponsored Brands (ASIN/categoria/brand) con BID e stato ATTUALI. Il target_id serve per ads_update_sb_target_bid. NON ritorna performance: usa execute_sql sul data-hub. Elenco vuoto = nessun target SB su questo profilo: dillo, NON inventare target.

Read-only: ad group Sponsored Display — id, nome, stato, campagna di appartenenza e defaultBid (l'offerta dell'ad group, la leva di ottimizzazione SD). Filtra con campaign_id_filter.

LIVE: campagne Sponsored Display (SD) ESISTENTI — name, campaignId, state (enabled|paused|archived), budget giornaliero, tactic (T00020 contestuale | T00030 audiences), costType (cpc|vcpm), bidOptimization. Vendooly non CREA campagne SD (servono audiences/creatives/Brand Registry): legge e aggiorna quelle già create da Amazon Ads console. NON ritorna performance: per ACoS/spesa SD usa execute_sql su fact_campaign_daily (ad_product='SD').

Read-only list of Sponsored Products ad groups (id, name, state, default bid)

READ-ONLY. Elenca i SEGMENTI DI PUBBLICO utilizzabili per i moltiplicatori di bid delle campagne Sponsored Products (audience bid adjustments, disponibili in IT/DE/FR/ES/UK). source: "amazon" (default: pubblici costruiti da Amazon, es. chi ha già comprato dal brand, chi ha cliccato o messo nel carrello, alta probabilità di acquisto), "amc" (pubblici creati in Amazon Marketing Cloud) o "all". search = filtro testuale opzionale. Ritorna audience_id, name, description, source. Gli audience_id vanno passati a ads_update_sp_audience_bidding; i segmenti già impostati su una campagna si leggono in ads_list_sp_campaigns (audience_adjustments). NON inventare audience_id: se la lista è vuota dillo all'utente.

LIVE: stato corrente delle campagne SP. Campi chiave per campagna: name, campaignId, state, targetingType (AUTO|MANUAL) e daily_budget = budget giornaliero NUMERICO nella valuta del marketplace (es. 50, 150). NON esiste un "bid" a livello campagna (i bid sono su keyword/target). Usa per VERIFICARE prima di agire o per avere nomi/ID. NON ritorna performance: per ACoS/spesa/ROAS/vendite/click usa execute_sql su fact_campaign_daily. Espone anche bidding_strategy e placement_adjustments = moltiplicatori % ATTUALI per placement (PLACEMENT_TOP | PLACEMENT_REST_OF_SEARCH | PLACEMENT_PRODUCT_PAGE | SITE_AMAZON_BUSINESS): per la PERFORMANCE per placement (spesa/ACoS/vendite Top of Search vs Product Pages vs Rest of Search) usa execute_sql su fact_campaign_placement_daily. audience_adjustments = moltiplicatori % ATTUALI per SEGMENTO DI PUBBLICO [{audience_id, percentage}] (nomi con ads_list_sp_audiences, modifica con ads_update_sp_audience_bidding).

LIVE: keyword SP con bid e stato ATTUALI — per agire o verificare. NON ritorna performance: per spesa/vendite/ACoS o keyword che sprecano usa execute_sql su fact_keyword_daily.

List SP negative keywords

List SP negative product targets

READ-ONLY LIVE. Elenco SP completo di default (all_pages=true), con ASIN/SKU, stato, nomi e stati di campagna e gruppo. Filtri esatti. all_pages=false legge una pagina Amazon: continuare con next_token anche se vuota dopo i filtri ASIN/SKU. Per trovare tutti gli ASIN scoperti usare ads_catalog_coverage.

List SP targeting clauses — SIA i target MANUAL (ASIN/categoria) SIA i 4 gruppi AUTO che Amazon genera da solo nelle campagne AUTO. Ogni clause ritorna il suo targetId, lo state e (se impostato) il bid. Mappatura gruppi AUTO (expression.type → nome UI): QUERY_HIGH_REL_MATCHES=close-match, QUERY_BROAD_REL_MATCHES=loose-match, ASIN_SUBSTITUTE_RELATED=substitutes, ASIN_ACCESSORY_RELATED=complements. PER CAMBIARE IL BID DI UN GRUPPO AUTO: chiama questo tool con campaign_id → prendi il targetId del gruppo → ads_update_sp_target_bid(target_id, bid). NON usare ads_create_* sulle AUTO (i target esistono già).

READ-ONLY. Cross-references catalog days of cover (30d cached velocity) with active SP product ads: finds where you are paying for clicks on products close to stock-out. Use for "am I wasting ads budget?", "are ads pushing products that are running out?".

Aggiorna un ad group Sponsored Brands (SB) ESISTENTE (es. stato ENABLED|PAUSED). NON crea ad group nuovi.

Aggiorna una o PIÙ campagne Sponsored Brands (SB) ESISTENTI: budget giornaliero, stato (ENABLED|PAUSED) e OTTIMIZZAZIONE DELL'OFFERTA. Per ottimizzare senza tagliare volume NON strozzare il budget: usa i moltiplicatori per posizionamento con patches.bid_adjustments_by_placement=[{placement, percentage}] — placement (enum verificato): TOP_OF_SEARCH | DETAIL_PAGE | HOME | OTHER (alias comodi: top, detail_page, home, other); percentage = aumento % dell'offerta su quella posizione, SOLO valori positivi (0 o più): dal 15/6/2026 Amazon NON accetta più moltiplicatori SB negativi e il tool li rifiuta prima di chiamare Amazon. Per spendere meno su una posizione abbassa i bid di keyword/target (ads_update_sb_keyword_bid/ads_update_sb_target_bid) e alza le altre posizioni. Passare i moltiplicatori implica bid_optimization=false (ottimizzazione Amazon spenta — richiesto da Amazon); con bid_optimization=true/AUTO ottimizza Amazon e i moltiplicatori non servono. SINGOLA: campaign_id + patches. BATCH: items=[{campaign_id, daily_budget?, state?, bid_adjustments_by_placement?}], MAX 25. Esito verificato per-id e PER-PLACEMENT (read-after-write). NON crea campagne nuove.

Aggiorna il BID di una o PIÙ keyword Sponsored Brands. È la leva per OTTIMIZZARE una campagna SB invece di spegnerla o strozzarne il budget. keyword_id si ottiene da ads_list_sb_keywords. SINGOLA: keyword_id + bid. BATCH (consigliato): items=[{keyword_id, bid}], MAX 25. Esito verificato per-id (read-after-write).

Aggiorna lo stato (ENABLED|PAUSED|ARCHIVED) di una o PIÙ keyword Sponsored Brands. SINGOLA: keyword_id + state. BATCH: items=[{keyword_id, state}], MAX 25. Esito verificato per-id.

Aggiorna il BID di uno o PIÙ product target Sponsored Brands. Insieme a ads_update_sb_keyword_bid e ai moltiplicatori per posizionamento di ads_update_sb_campaign è il modo per OTTIMIZZARE SB (invece di limitarsi a spegnere o tagliare il budget). target_id da ads_list_sb_targets. SINGOLA: target_id + bid. BATCH: items=[{target_id, bid}], MAX 25. Esito verificato per-id.

Aggiorna lo stato (ENABLED|PAUSED|ARCHIVED) di uno o PIÙ product target Sponsored Brands. SINGOLA: target_id + state. BATCH: items=[{target_id, state}], MAX 25. Esito verificato per-id.

Aggiorna uno o PIÙ ad group Sponsored Display: BID (defaultBid) e/o stato (enabled|paused). Su SD il bid dell'ad group è la leva principale di ottimizzazione. SINGOLA: ad_group_id + bid/state. BATCH: items=[{ad_group_id, bid?, state?}], MAX 25. Esito verificato per-id.

Aggiorna una o PIÙ campagne Sponsored Display ESISTENTI: budget giornaliero e/o stato (enabled|paused). SINGOLA: campaign_id + daily_budget/state. BATCH: items=[{campaign_id, daily_budget?, state?}], MAX 25. Esito verificato per-id (read-after-write). NON crea campagne SD.

Update a SP ad group

Imposta i MOLTIPLICATORI PER SEGMENTO DI PUBBLICO di UNA campagna Sponsored Products (dynamicBidding.shopperCohortBidding): aggiunge o modifica (set=[{audience_id, percentage}]), toglie (remove=[audience_id]) o azzera tutto (clear_all=true). percentage = aumento % del bid, INTERO 0-900: i segmenti possono solo ALZARE il bid, mai abbassarlo. Si applica SOPRA il moltiplicatore di placement (es. bid 1€, Top of Search +50% = 1,50€, pubblico +100% = 3€). Massimo 10 segmenti per campagna. Il tool RILEGGE la campagna live, fonde le modifiche con i segmenti esistenti e rimanda INVARIATI i moltiplicatori di placement. FLUSSO: (1) chiamata senza confirm = ANTEPRIMA prima→dopo per segmento, nulla viene scritto; (2) mostra la tabella all'utente; (3) solo dopo il suo ok richiama con gli STESSI argomenti + confirm=true; esito verificato con rilettura (segmenti e placement). audience_id da ads_list_sp_audiences. Regola pratica: solo su campagne con ACoS entro il target, misurando 14-30 giorni.

Aggiorna una o PIÙ campagne SP. SINGOLA: campaign_id + patches (patches.daily_budget numero → convertito nel payload v3 budget{budgetType:DAILY,budget}; patches.state ENABLED|PAUSED; patches.placement_bidding = MOLTIPLICATORI per placement [{placement, percentage 0-900}] con placement PLACEMENT_TOP|PLACEMENT_REST_OF_SEARCH|PLACEMENT_PRODUCT_PAGE|SITE_AMAZON_BUSINESS (alias top/rest_of_search/product_page/business); patches.bidding_strategy LEGACY_FOR_SALES|AUTO_FOR_SALES|MANUAL|RULE_BASED). Flusso placement: execute_sql su fact_campaign_placement_daily (performance per placement) → ads_list_sp_campaigns (placement_adjustments attuali) → anteprima prima→dopo → conferma → questo tool; esito verificato per placement (read-after-write). BATCH (consigliato per agire su più campagne in una volta, es. "sistema 10 campagne"): items=[{campaign_id, daily_budget?, state?, placement_bidding?}], ogni campagna con valori diversi, MAX 25. Esito verificato per-id (budget e/o stato). I SEGMENTI DI PUBBLICO non si toccano qui (usa ads_update_sp_audience_bidding): quando cambi placement o strategia il tool rilegge la campagna e mantiene i segmenti esistenti.

Aggiorna il bid di una o PIÙ keyword SP. SINGOLA: keyword_id + bid. BATCH (consigliato per agire su molte keyword in una volta — meno chiamate, niente raffica): items=[{keyword_id, bid}], ogni keyword può avere un bid diverso, MAX 25 per chiamata. Esito verificato PER-ID (read-after-write).

Aggiorna lo stato (ENABLED/PAUSED) di una o PIÙ keyword SP. SINGOLA: keyword_id + state. BATCH: items=[{keyword_id, state}], MAX 25 per chiamata. Esito verificato PER-ID.

Aggiorna il bid di uno o PIÙ target SP (MANUAL ASIN/categoria o i 4 gruppi AUTO close/loose/substitutes/complements). Il target_id si ottiene da ads_list_sp_targets; è QUESTA (non ads_create_*) la via per modulare i bid dei gruppi auto su una campagna AUTO già esistente. SINGOLA: target_id + bid. BATCH (consigliato per molti target): items=[{target_id, bid}], ognuno con bid diverso, MAX 25. Esito verificato per-id.

Aggiorna lo stato (ENABLED/PAUSED) di uno o PIÙ target SP. SINGOLA: target_id + state. BATCH: items=[{target_id, state}], MAX 25. Esito verificato per-id.

READ-ONLY. Copertura A+ Content del catalogo: quali ASIN hanno un documento A+ APPROVED (= visibile al cliente) e quali no, con i buchi ORDINATI per peso commerciale (unità vendute a 30 giorni) — quindi "quali pagine che vendono davvero sono senza A+". Segnala anche i documenti REJECTED (lavoro già fatto mai andato online, il recupero più rapido) e quelli in DRAFT/SUBMITTED. LIMITE DA DICHIARARE SEMPRE ALL'UTENTE: misura i documenti A+ DI QUESTO seller — un ASIN può mostrare l'A+ del brand owner e comparire comunque come scoperto; l'A+ è inoltre PER MARKETPLACE (IT/DE/FR/ES sono documenti distinti, vanno auditati un outpost alla volta). La creazione/modifica A+ via API NON è implementata: le correzioni si fanno da Seller Central. Il catalogo viene dal data-hub (`catalog_source`): se il seller non è ancora sincronizzato risponde `catalog_not_ready` con le alternative (list_aplus_documents / get_aplus_document), non un errore muto.

Run catalog quality audit

Audit compliance/GPSR del catalogo (EU/IT). Per ogni SKU verifica gli attributi compliance REALI del suo product type (schema-aware): manufacturer, rtip_manufacturer_contact_information (contatto fabbricante), country_of_origin, safety_warning, safety_data_sheet_url e — dove il product type li prevede — i GPSR: gpsr_safety_attestation, gpsr_manufacturer_reference, dsa_responsible_party_address (responsabile EU). Incrocia gli ISSUE Amazon a tema compliance (Amazon dice cosa manca/è rifiutato). Ritorna gli SKU con gap, priorità (alta = issue ERROR Amazon o GPSR mancante), conteggi per attributo e i gap più frequenti. Flagga "mancante" SOLO se il product type prevede davvero l'attributo. NB: i numeri EPR (Francia / LUCID DE / RAEE-batterie) sono a livello ACCOUNT in Seller Central → Conformità, NON attributi listing: SP-API ne legge l'alert ma non li imposta. Per correggere usa update_listing. READ-ONLY. mode="full" = verifica TUTTI I REQUISITI del product type: ogni attributo `required` dello schema Amazon della categoria (inclusi i requisiti di categoria, es. pharma/parafarmacia) + TUTTE le issue Amazon di qualsiasi categoria. Usa mode="full" quando l'utente chiede di verificare "tutti i requisiti di conformità" dei prodotti; il default (standard) resta il check rapido compliance/GPSR.

Audit all listings for Amazon title limit (75 chars, enforced from July/August 2026 — i titoli non conformi vengono RISCRITTI dall'IA di Amazon, solo i brand registrati hanno 14 giorni di review). Returns titles over the limit with excess character count + bullet/highlight counts per SKU, più la fascia at_risk (73–75 char, conformi ma senza margine). L'azione per un titolo troppo lungo è ACCORCIARLO (action=TRIM_TITLE): gli Item Highlights (attributo ufficiale title_differentiation, legacy item_highlights — l'audit li legge entrambi) NON rendono conforme un titolo lungo, e su molti marketplace (es. amazon.it) non sono nemmeno un attributo scrivibile (lì la leva sono i bullet_point). highlight_count è indicativo, non un'azione. Per prioritizzare le fix incrocia gli SKU con le vendite 30g dal data-hub (execute_sql su fact_sku_daily_sales × dim_product).