adloop 0.35.0__tar.gz → 0.35.1__tar.gz

{adloop-0.35.0 → adloop-0.35.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.35.0
+Version: 0.35.1
 Summary: The AI command center for Google Ads, Reddit Ads, GA4, and tracking code.
 Keywords: mcp,google-ads,reddit-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose

{adloop-0.35.0 → adloop-0.35.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.35.0"
+version = "0.35.1"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 requires-python = ">=3.11"

{adloop-0.35.0 → adloop-0.35.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.35.0"
+version = "0.35.1"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 authors = [

{adloop-0.35.0 → adloop-0.35.1}/src/adloop/ads/assets.py

@@ -1415,13 +1415,14 @@ def draft_promotion(
     scope: str = "",
     language_code: str = "",
     currency_code: str = "",
+    ad_schedule: list[dict] | None = None,
     **promotion,
 ) -> dict:
     """Draft a promotion asset linked to an ad group, a campaign or the account.
 
     ``promotion`` takes promotion_target, final_url, money_off or percent_off,
     promotion_code or orders_over_amount, occasion, discount_modifier and the
-    four dates.
+    four dates. ``ad_schedule`` limits the hours it shows.
     """
     from adloop.safety.preview import ChangePlan, store_plan
 
@@ -1430,6 +1431,8 @@ def draft_promotion(
     scope, campaign_id, ad_group_id, errors = resolve_scope(scope, campaign_id, ad_group_id)
     fields, parse_errors = _promotion_input(**promotion)
     fields["language_code"] = _language(language_code, errors)
+    fields["ad_schedule"], schedule_errors = _validate_schedule(ad_schedule or [])
+    errors += schedule_errors
     errors += parse_errors or _check_promotion(fields)
     if errors:
         return {"error": "Validation failed", "details": errors}
@@ -1456,6 +1459,8 @@ def draft_promotion(
     preview = plan.to_preview()
     preview["warnings"] = [*warnings, *_promotion_warnings(fields), *url_warnings] + (
         [_account_scope_warning("promotions")] if scope == "account" else [])
+    if fields["ad_schedule"]:
+        preview["warnings"].append(_time_zone_note(_account_settings(config, customer_id)["time_zone"]))
     return preview
 
 
@@ -1472,8 +1477,10 @@ _PROMOTION_FIELDS = {
     "discount_modifier": "asset.promotion_asset.discount_modifier",
     "language_code": "asset.promotion_asset.language_code",
     **{field: f"asset.promotion_asset.{field}" for field in _DATE_FIELDS},
+    "ad_schedule": "asset.promotion_asset.ad_schedule_targets",
 }
-_CLEARABLE = ("promotion_code", "orders_over_amount", "occasion", "discount_modifier", *_DATE_FIELDS)
+_CLEARABLE = ("promotion_code", "orders_over_amount", "occasion", "discount_modifier", *_DATE_FIELDS,
+              "ad_schedule")
 
 
 def _promotion_from_google(raw: dict) -> dict:
@@ -1490,6 +1497,7 @@ def _promotion_from_google(raw: dict) -> dict:
         "discount_modifier": raw["discount_modifier"],
         "language_code": raw["language_code"],
         **{field: raw[field] for field in _DATE_FIELDS},
+        "ad_schedule": _schedule_from_google(raw["ad_schedule"]),
     }
 
 
@@ -1501,9 +1509,14 @@ def update_promotion(
     language_code: str = "",
     currency_code: str = "",
     clear_fields: list[str] | None = None,
+    ad_schedule: list[dict] | None = None,
     **promotion,
 ) -> dict:
-    """Draft an in-place edit of a promotion asset; fields not passed stay as they are."""
+    """Draft an in-place edit of a promotion asset; fields not passed stay as they are.
+
+    A non-empty ``ad_schedule`` replaces the promotion's schedule;
+    ``clear_fields=["ad_schedule"]`` removes it.
+    """
     if blocked := _blocked("update_promotion", config):
         return blocked
     asset_id = _clean(asset_id)
@@ -1511,6 +1524,10 @@ def update_promotion(
     passed, parse_errors = _promotion_input(**promotion)
     errors += parse_errors
     passed = {k: v for k, v in passed.items() if v}
+    windows, schedule_errors = _validate_schedule(ad_schedule or [])
+    errors += schedule_errors
+    if windows:
+        passed["ad_schedule"] = windows
     if _clean(language_code):
         passed["language_code"] = _language(language_code, errors)
     clear = [_clean(f).lower() for f in clear_fields or []]
@@ -1539,7 +1556,7 @@ def update_promotion(
     if "orders_over_amount" in passed:
         merged["promotion_code"] = ""
     for field in clear:
-        merged[field] = 0.0 if field == "orders_over_amount" else ""
+        merged[field] = {"orders_over_amount": 0.0, "ad_schedule": []}.get(field, "")
     errors = _check_promotion(merged)
     if errors:
         return {"error": "Validation failed", "details": errors}
@@ -1565,6 +1582,10 @@ def update_promotion(
                          {"set": changed, "promotion": merged},
                          {k: current[k] for k in changed}, pinned={k: raw[k] for k in _PROMOTION_FIELDS})
     preview["warnings"] += warnings + _promotion_warnings(merged)
+    if "ad_schedule" in changed:
+        preview["warnings"].append(
+            _time_zone_note(_account_settings(config, customer_id)["time_zone"]) if merged["ad_schedule"]
+            else "Without a schedule the promotion shows at all hours the campaign serves.")
     return preview
 
 
@@ -1589,6 +1610,10 @@ def _populate_promotion(client, asset, promo: dict) -> None:
     for field in _DATE_FIELDS:
         if promo.get(field):
             setattr(p, field, promo[field])
+    for window in promo.get("ad_schedule") or []:
+        info = client.get_type("AdScheduleInfo")
+        _populate_schedule(client, info, window)
+        p.ad_schedule_targets.append(info)
     asset.final_urls.append(promo["final_url"])
 
 
@@ -1638,6 +1663,12 @@ def _apply_update_promotion(client, cid: str, changes: dict) -> dict:
                 if promo[field]:
                     setattr(p, field, promo[field])
                 paths.append(f"promotion_asset.{field}")
+        if "ad_schedule" in changed:  # replaces the whole list; empty clears it
+            for window in promo["ad_schedule"]:
+                info = client.get_type("AdScheduleInfo")
+                _populate_schedule(client, info, window)
+                p.ad_schedule_targets.append(info)
+            paths.append("promotion_asset.ad_schedule_targets")
         return list(dict.fromkeys(paths))
 
     return _apply_asset_update(client, cid, changes["asset_id"], set_fields)

{adloop-0.35.0 → adloop-0.35.1}/src/adloop/ads/write.py

@@ -2267,8 +2267,11 @@ def update_campaign(
     )
     errors.extend(alias_errors)
 
+    campaign_id = str(campaign_id or "").strip()
     if not campaign_id:
         errors.append("campaign_id is required")
+    elif not campaign_id.isdigit():
+        errors.append(f"campaign_id must be numeric, got '{campaign_id}'")
 
     bs = bidding_strategy.upper() if bidding_strategy else ""
     if bs and bs not in _VALID_BIDDING_STRATEGIES:
@@ -2361,7 +2364,46 @@ def update_campaign(
                 'entity_type="campaign_criterion".'
             )
 
+    # A budget can be shared by several campaigns, and a portfolio bid
+    # strategy too: say who else a budget change reaches, and that a bidding
+    # change takes the campaign out of its portfolio. Both need a double
+    # confirmation, and apply re-checks the state the preview showed.
+    shared: dict = {}
+    requires_double_confirm = False
+    if daily_budget or bs or max_cpc:
+        shared = _budget_and_bidding_context(
+            config, customer_id, campaign_id,
+            budget=bool(daily_budget), portfolio=bool(bs or max_cpc),
+        )
+        if shared is None:
+            return {"error": f"Campaign {campaign_id} was not found in this account"}
+    if daily_budget and shared["budget_shared_with"]:
+        others = ", ".join(f"'{c['name']}' ({c['id']})" for c in shared["budget_shared_with"])
+        warnings.append(
+            f"Shared budget: '{shared['budget_name']}' also funds {others}. The new "
+            "amount is the daily budget of ALL of them together, not of this campaign "
+            "alone. To change only this campaign, give it its own budget in Google Ads first."
+        )
+        requires_double_confirm = True
+    if (bs or max_cpc) and shared.get("bidding_strategy_resource"):
+        others = ", ".join(f"'{c['name']}'" for c in shared["portfolio_shared_with"]) or "no other campaigns"
+        warnings.append(
+            f"Portfolio bid strategy: this campaign uses '{shared['portfolio_name']}' "
+            f"(also used by {others}). This change gives the campaign its own strategy "
+            "and takes it out of the portfolio; the portfolio and its other campaigns stay "
+            "as they are. To change the portfolio's targets for all of them, edit it in Google Ads."
+        )
+        requires_double_confirm = True
+
     changes: dict = {"campaign_id": campaign_id}
+    if daily_budget:
+        changes["current_daily_budget"] = shared["budget_amount"]
+        changes["budget_name"] = shared["budget_name"]
+        # Pinned: apply refuses if the campaign's budget or its sharing changed.
+        changes["budget_resource"] = shared["budget_resource"]
+        changes["budget_shared_with"] = sorted(c["id"] for c in shared["budget_shared_with"])
+    if bs or max_cpc:
+        changes["bidding_strategy_resource"] = shared["bidding_strategy_resource"]
     if bs:
         changes["bidding_strategy"] = bs
     if target_cpa:
@@ -2387,6 +2429,7 @@ def update_campaign(
         entity_id=campaign_id,
         customer_id=customer_id,
         changes=changes,
+        requires_double_confirm=requires_double_confirm,
     )
     store_plan(plan)
     preview = plan.to_preview()
@@ -3094,6 +3137,95 @@ def _campaign_bidding_strategy(
     return rows[0].get("campaign.bidding_strategy_type")
 
 
+_SHARED_RESOURCE_RE = re.compile(r"customers/\d+/(campaignBudgets|biddingStrategies)/\d+")
+
+
+def _campaigns_using(config: AdLoopConfig, customer_id: str, field: str, resource: str,
+                     campaign_id: str) -> list[dict]:
+    """Other non-removed campaigns whose ``campaign.<field>`` is ``resource``."""
+    from adloop.ads.gaql import execute_query
+
+    if not _SHARED_RESOURCE_RE.fullmatch(resource or ""):
+        return []
+    rows = execute_query(config, customer_id, (
+        f"SELECT campaign.id, campaign.name FROM campaign WHERE campaign.{field} = '{resource}' "
+        "AND campaign.status != 'REMOVED'"))
+    return [{"id": str(r.get("campaign.id")), "name": r.get("campaign.name") or ""}
+            for r in rows if str(r.get("campaign.id")) != str(campaign_id)]
+
+
+def _budget_and_bidding_context(
+    config: AdLoopConfig, customer_id: str, campaign_id: str, *, budget: bool, portfolio: bool
+) -> dict | None:
+    """The campaign's budget and portfolio bid strategy, with who else uses them.
+
+    None when the campaign does not exist. Read failures propagate: whether a
+    budget is shared is a safety question, not a decoration.
+    """
+    from adloop.ads.gaql import execute_query
+
+    rows = execute_query(config, customer_id, (
+        "SELECT campaign.id, campaign.campaign_budget, campaign.bidding_strategy, "
+        "campaign_budget.name, campaign_budget.amount_micros "
+        f"FROM campaign WHERE campaign.id = {campaign_id}"))
+    if not rows:
+        return None
+    row = rows[0]
+    budget_rn = row.get("campaign.campaign_budget") or ""
+    portfolio_rn = row.get("campaign.bidding_strategy") or ""
+    context = {
+        "budget_resource": budget_rn,
+        "budget_name": row.get("campaign_budget.name") or "",
+        "budget_amount": (row.get("campaign_budget.amount_micros") or 0) / 1_000_000,
+        "budget_shared_with": (
+            _campaigns_using(config, customer_id, "campaign_budget", budget_rn, campaign_id) if budget else []),
+        "bidding_strategy_resource": portfolio_rn,
+        "portfolio_name": "",
+        "portfolio_shared_with": [],
+    }
+    if portfolio and portfolio_rn and _SHARED_RESOURCE_RE.fullmatch(portfolio_rn):
+        names = execute_query(config, customer_id, (
+            f"SELECT bidding_strategy.name FROM bidding_strategy WHERE bidding_strategy.resource_name = '{portfolio_rn}'"))
+        context["portfolio_name"] = (names[0].get("bidding_strategy.name") if names else "") or portfolio_rn
+        context["portfolio_shared_with"] = _campaigns_using(
+            config, customer_id, "bidding_strategy", portfolio_rn, campaign_id)
+    return context
+
+
+def _check_budget_and_bidding_unchanged(service, cid: str, changes: dict) -> None:
+    """Refuse when the budget or portfolio state the preview showed has moved."""
+    pins_budget = "budget_resource" in changes
+    pins_bidding = "bidding_strategy_resource" in changes
+    if not (pins_budget or pins_bidding):
+        return  # plans drafted before 0.35.1 carry no pins
+    campaign_id = changes["campaign_id"]
+    rows = list(service.search(customer_id=cid, query=(
+        "SELECT campaign.campaign_budget, campaign.bidding_strategy "
+        f"FROM campaign WHERE campaign.id = {campaign_id}")))
+    if not rows:
+        raise ValueError(f"Campaign {campaign_id} not found")
+    campaign = rows[0].campaign
+    moved = []
+    if pins_budget:
+        if campaign.campaign_budget != changes["budget_resource"]:
+            moved.append("it uses a different budget")
+        elif _SHARED_RESOURCE_RE.fullmatch(changes["budget_resource"] or ""):
+            sharing = sorted(
+                str(r.campaign.id) for r in service.search(customer_id=cid, query=(
+                    "SELECT campaign.id FROM campaign WHERE campaign.campaign_budget = "
+                    f"'{changes['budget_resource']}' AND campaign.status != 'REMOVED'"))
+                if str(r.campaign.id) != str(campaign_id))
+            if sharing != sorted(changes.get("budget_shared_with") or []):
+                moved.append("other campaigns joined or left its budget")
+    if pins_bidding and campaign.bidding_strategy != changes["bidding_strategy_resource"]:
+        moved.append("its portfolio bid strategy changed")
+    if moved:
+        raise RuntimeError(
+            f"Campaign {campaign_id} changed after this preview ({'; '.join(moved)}); "
+            "nothing was sent. Draft the change again so the preview shows who it reaches."
+        )
+
+
 def _existing_negative_geo_exclusions(
     config: AdLoopConfig, customer_id: str, campaign_id: str
 ) -> list[str]:
@@ -4264,6 +4396,7 @@ def _apply_update_campaign(client: object, cid: str, changes: dict) -> dict:
 
     campaign_id = changes["campaign_id"]
     resource_name = campaign_service.campaign_path(cid, campaign_id)
+    _check_budget_and_bidding_unchanged(service, cid, changes)
 
     # Bid strategy and campaign-level setting changes
     bs = changes.get("bidding_strategy")

{adloop-0.35.0 → adloop-0.35.1}/src/adloop/rules/adloop.md

@@ -294,8 +294,8 @@ Conversions that happen offline (a sales call, a lead that turned into a deal) g
 | `draft_call_asset` | Create a call asset (phone number shown with the ads) for an ad group, a campaign or the account | `phone_number`, `country_code` (REQUIRED, ISO alpha-2), `campaign_id` or `ad_group_id` or `scope="account"`; optional `call_conversion_action_id`, `ad_schedule` |
 | `update_call_asset` | Edit a call asset IN PLACE: number, call conversion action / reporting state, schedule | `asset_id`; `phone_number` needs `country_code`; `ad_schedule` replaces the schedule, `clear_ad_schedule=true` removes it |
 | `add_ad_schedule` | Add ad schedule windows to a campaign; existing windows stay | `campaign_id`, `schedule` list of {day_of_week, start_hour, end_hour, start_minute/end_minute 0/15/30/45}, whole numbers; no overlaps, at most 6 a day. A campaign's FIRST schedule needs a double confirmation |
-| `draft_promotion` | Create a promotion asset ("20% off winter tyres") for an ad group, a campaign or the account | `promotion_target` (≤20), `final_url`, `language_code` (REQUIRED), `money_off` or `percent_off`; optional `promotion_code` (≤15) or `orders_over_amount`, `occasion`, `discount_modifier` UP_TO, dates; amounts in the account currency unless `currency_code` |
-| `update_promotion` | Edit a promotion IN PLACE; fields not passed stay | `asset_id` plus the fields to change; `money_off`/`percent_off` and `promotion_code`/`orders_over_amount` replace each other; `clear_fields` removes optional ones |
+| `draft_promotion` | Create a promotion asset ("20% off winter tyres") for an ad group, a campaign or the account | `promotion_target` (≤20), `final_url`, `language_code` (REQUIRED), `money_off` or `percent_off`; optional `promotion_code` (≤15) or `orders_over_amount`, `occasion`, `discount_modifier` UP_TO, dates, `ad_schedule` (hours it shows); amounts in the account currency unless `currency_code` |
+| `update_promotion` | Edit a promotion IN PLACE; fields not passed stay | `asset_id` plus the fields to change; `money_off`/`percent_off` and `promotion_code`/`orders_over_amount` replace each other; `ad_schedule` replaces its schedule; `clear_fields` removes optional ones (incl. `ad_schedule`) |
 | `draft_price_asset` | Create a price asset (3-8 offerings) for an ad group, a campaign or the account | `offerings` [{header ≤25, description ≤25, price, final_url, unit}], `price_type`, `language_code` (both REQUIRED); `price_qualifier` FROM/UP_TO/AVERAGE optional; account currency unless `currency_code` |
 | `draft_image_assets` | Create image assets for a campaign from local files, public image URLs or uploads (does NOT publish) | `campaign_id`, `image_paths` (local PNG/JPEG/GIF files; not on a hosted server), `image_urls` (public http(s) image links, ≤5120 KB; re-checked at apply — if the image changed since the preview, draft again) and/or `upload_ids` (`up_...` from `upload_images` / `list_uploads`) |
 | `draft_sitelinks` | Create sitelink extensions for a campaign (does NOT publish) | `campaign_id`, `sitelinks` list of {link_text ≤25 chars, final_url, description1 ≤35 chars, description2 ≤35 chars} |
@@ -363,6 +363,7 @@ Same draft → preview → `confirm_and_apply` gate; the plan carries `platform:
 - `display_network_enabled` is the canonical Search display-expansion flag. `display_expansion_enabled` is only a compatibility alias and should be normalized away before presenting the plan to the user.
 - `update_ad_group` is the right tool for later MANUAL_CPC bid changes. Use `update_campaign` for TARGET_SPEND (Maximize Clicks) `max_cpc` changes.
 - Ad-group pause/enable is already handled by `pause_entity` / `enable_entity` with `entity_type="ad_group"`; do not invent a separate pause tool.
+- `update_campaign` budget changes show the current amount (`current_daily_budget`). A shared budget (`budget_shared_with` lists the other campaign IDs) or a portfolio bid strategy makes the plan require double confirmation, and apply refuses if the budget, its sharing or the portfolio changed after the preview.
 - `update_campaign` replaces POSITIVE geo/language targets entirely (not append). Pass the full desired list. NEGATIVE geo exclusions (criteria with `negative=TRUE`) are **preserved** across a positive-geo replacement — they survive the swap. The preview surfaces preserved negative geo IDs in `preserved_negative_geo_target_ids` so the change is auditable. To ADD negative geo exclusions (e.g. exclude a city inside a targeted state), use `add_negative_locations` — do not try to express exclusions through `geo_target_ids`. To remove a negative geo exclusion explicitly, use `remove_entity` with `entity_type="campaign_criterion"`.
 - **Asset scope:** callouts and snippets link where the id points (`ad_group_id` → ad group, `campaign_id` → campaign). Account-wide (`scope="account"`) reaches every campaign without assets of its own; use it only when the user asks for account level. **Asset edits** (`update_callout`, `update_sitelink`, `update_structured_snippet`) change the asset everywhere it is linked; check with GAQL (`campaign_asset`, `ad_group_asset`, `customer_asset`) where else it is used before editing a shared asset. If the apply reports the asset changed in Google Ads since the preview, draft again.
 - **Call assets, schedules, promotions and prices.** Never guess `country_code` or `language_code`: take them from the number and the landing page, and ask when unclear. Money amounts are in the account currency (the preview names it); pass `currency_code` only for a different one. Ad schedule hours are in the **account time zone** (the previews show it), not the searcher's: convert the user's local hours first. A campaign without a schedule serves at all hours, so its first `add_ad_schedule` windows switch off every other hour and day: say so, the preview needs a double confirmation. To change a window, remove the old one with `remove_entity` (`entity_type="campaign_criterion"`, the `remove_id` from the preview), then add the new one. Prices must match the landing page or Google disapproves them.
@@ -526,6 +527,7 @@ Most websites (especially in the EU) use a GDPR cookie consent banner. This has
    - If changing to MANUAL_CPC: warn about the trade-offs (no automation, requires constant monitoring)
    - If removing geo or language targets: warn that this broadens targeting and may waste budget
    - If the campaign is in a learning phase: warn that changes will restart the learning phase
+   - **Shared budgets and portfolio strategies:** a budget change on a SHARED budget changes the daily budget of every campaign using it, and a bidding change on a campaign in a portfolio bid strategy takes it out of the portfolio. The preview names the other campaigns and asks for a double confirmation; tell the user plainly before they confirm. If they meant only this campaign, its own budget has to be set up in Google Ads first
 4. Call `update_campaign` with only the parameters that need to change
 5. Present the preview — clearly show what's changing (old → new)
 6. Wait for explicit user approval before calling `confirm_and_apply`

{adloop-0.35.0 → adloop-0.35.1}/src/adloop/server.py

@@ -3337,7 +3337,11 @@ def update_campaign(
 
     Only the parameters passed are changed; omitted ones stay as they are, and at
     least one change is required. Replacing geo targets keeps the campaign's
-    negative geo exclusions (the preview lists them).
+    negative geo exclusions (the preview lists them). A budget change shows the
+    current amount; when the budget is shared with other campaigns, the
+    preview names them and needs a double confirmation, because the new amount
+    covers all of them. A bidding change on a campaign in a portfolio bid
+    strategy takes it out of the portfolio, also with a double confirmation.
 
     Returns a preview with a plan_id plus any warnings; nothing changes until
     confirm_and_apply applies it.
@@ -3354,7 +3358,8 @@ def update_campaign(
         target_roas: Target ROAS as a ratio (e.g. 4.0 = 400%); required if
             bidding_strategy is TARGET_ROAS. 0 leaves it unchanged.
         daily_budget: New daily budget in the account's currency (not micros),
-            at most the config's max_daily_budget. 0 leaves it unchanged.
+            at most the config's max_daily_budget. 0 leaves it unchanged. On a
+            shared budget it is the amount for every campaign sharing it.
         geo_target_ids: REPLACES all positive geo targets; must not be empty
             when given. Common IDs: "2276" Germany, "2040" Austria, "2756"
             Switzerland, "2840" USA, "2826" UK.
@@ -4425,6 +4430,7 @@ def draft_promotion(
     end_date: str = "",
     redemption_start_date: str = "",
     redemption_end_date: str = "",
+    ad_schedule: _DictList = [],  # noqa: B006
     customer_id: str = "",
 ) -> dict:
     """Draft a promotion asset ("20% off winter tyres") — returns a PREVIEW.
@@ -4461,6 +4467,10 @@ def draft_promotion(
         end_date: Last day the promotion shows, YYYY-MM-DD.
         redemption_start_date: First day the offer can be redeemed, YYYY-MM-DD.
         redemption_end_date: Last day the offer can be redeemed, YYYY-MM-DD.
+        ad_schedule: Optional windows when the promotion shows, each
+            {day_of_week: MONDAY..SUNDAY, start_hour: 0-23, end_hour: 0-24,
+            start_minute/end_minute: 0, 15, 30 or 45}. Hours are in the
+            account time zone.
         customer_id: Google Ads customer ID (digits, dashes optional). Defaults to
             the configured account.
     """
@@ -4486,6 +4496,7 @@ def draft_promotion(
         end_date=end_date,
         redemption_start_date=redemption_start_date,
         redemption_end_date=redemption_end_date,
+        ad_schedule=ad_schedule,
     )
 
 
@@ -4508,6 +4519,7 @@ def update_promotion(
     redemption_start_date: str = "",
     redemption_end_date: str = "",
     clear_fields: _StrList = [],  # noqa: B006
+    ad_schedule: _DictList = [],  # noqa: B006
     customer_id: str = "",
 ) -> dict:
     """Draft changing a promotion asset in place — returns a PREVIEW.
@@ -4538,7 +4550,10 @@ def update_promotion(
         redemption_end_date: Last day the offer can be redeemed, YYYY-MM-DD.
         clear_fields: Optional fields to remove: promotion_code,
             orders_over_amount, occasion, discount_modifier, start_date,
-            end_date, redemption_start_date, redemption_end_date.
+            end_date, redemption_start_date, redemption_end_date,
+            ad_schedule.
+        ad_schedule: Windows that replace the promotion's whole schedule (same
+            shape as draft_promotion). Empty leaves the schedule as it is.
         customer_id: Google Ads customer ID (digits, dashes optional). Defaults to
             the configured account.
     """
@@ -4551,6 +4566,7 @@ def update_promotion(
         language_code=language_code,
         currency_code=currency_code,
         clear_fields=clear_fields,
+        ad_schedule=ad_schedule,
         promotion_target=promotion_target,
         final_url=final_url,
         money_off=money_off,