feat: add display_url support to create_ad_creative

display_url ("Use display URL") lets advertisers show a vanity/branding domain
to users while the real destination stays in link_url. It is carried on
asset_feed_spec.link_urls; setting it routes the creative through the
asset_feed_spec path. Works for both image and video creatives.

Author: nictuku

meta_ads_mcp/core/ads.py

@@ -1725,6 +1725,7 @@ async def create_ad_creative(
     image_hashes: Optional[List[str]] = None,
     video_id: Optional[Union[str, int]] = None,
     thumbnail_url: Optional[str] = None,
+    display_url: Optional[str] = None,
     optimization_type: Optional[str] = None,
     dynamic_creative_spec: Optional[Dict[str, Any]] = None,
     call_to_action_type: Optional[str] = None,
@@ -1820,6 +1821,12 @@ async def create_ad_creative(
                       a few seconds (poll with get_ad_video until video_status
                       is "ready") and retry, or pass thumbnail_url explicitly
                       (any public image URL works).
+        display_url: Optional vanity/branding URL shown to users ("Use display URL"
+                     in Ads Manager, e.g. "brand.example") while the real destination
+                     stays in link_url (e.g. "https://example.com/landing"). Requires
+                     link_url. Works for image and video creatives. Carried on
+                     asset_feed_spec.link_urls; setting it routes the creative through
+                     the asset_feed_spec path.
         optimization_type: Optional. Valid values:
                           - "DEGREES_OF_FREEDOM": FLEX (Advantage+) creatives where Meta auto-optimizes
                             across all asset combinations. At least one multi-variant asset field required.
@@ -2242,6 +2249,9 @@ async def create_ad_creative(
         use_asset_feed = bool(
             headlines or descriptions or messages or image_hashes or videos or images
             or optimization_type or asset_customization_rules
+            # display_url is only accepted on asset_feed_spec.link_urls, never in
+            # object_story_spec.video_data, so honoring it requires the AFS path.
+            or display_url
         )
 
         # Track whether `description` was provided but cannot be rendered in the
@@ -2502,7 +2512,12 @@ async def create_ad_creative(
                 # Lead-gen flows can omit a website link_url (lead_gen_form_id
                 # provides the destination), so guard link_urls on link_url.
                 if link_url:
-                    asset_feed_spec["link_urls"] = [{"website_url": link_url}]
+                    link_url_entry: Dict[str, Any] = {"website_url": link_url}
+                    # display_url ("Use display URL") rides on the link_urls entry —
+                    # the only place Meta accepts it for a creative.
+                    if display_url:
+                        link_url_entry["display_url"] = display_url
+                    asset_feed_spec["link_urls"] = [link_url_entry]
                 if optimization_type:
                     asset_feed_spec["optimization_type"] = optimization_type
 

tests/test_video_creatives.py

@@ -1683,3 +1683,93 @@ async def test_videos_array_proceeds_when_thumbnail_fetch_fails():
         # No thumbnail_url on the entry — graceful degradation.
         assert "thumbnail_url" not in videos_out[0]
         assert videos_out[0]["video_id"] == "vid_no_thumb"
+
+
+@pytest.mark.asyncio
+async def test_video_creative_with_display_url_uses_asset_feed_link_urls():
+    """display_url routes a video creative through asset_feed_spec.link_urls.
+
+    Meta only accepts display_url on asset_feed_spec.link_urls[].display_url, not
+    inside object_story_spec.video_data, so setting it forces the asset_feed_spec
+    path.
+    """
+
+    with patch('meta_ads_mcp.core.ads.make_api_request') as mock_api, \
+         patch('meta_ads_mcp.core.ads._discover_pages_for_account') as mock_discover:
+
+        mock_discover.return_value = {
+            "success": True,
+            "page_id": "123456789",
+            "page_name": "Test Page",
+        }
+
+        mock_api.side_effect = [
+            # 1) Auto-fetch video thumbnail (no thumbnail_url provided)
+            {"picture": "https://example.com/auto-thumb.jpg"},
+            # 2) POST create creative
+            {"id": "creative_display_url_1"},
+            # 3) GET creative details
+            {"id": "creative_display_url_1", "name": "Display URL Creative", "status": "ACTIVE"},
+        ]
+
+        result = await create_ad_creative(
+            account_id="act_123456",
+            video_id="vid_987654",
+            name="Display URL Ad",
+            link_url="https://example.com/landing",
+            display_url="brand.example",
+            message="Check out this video",
+            headline="Watch Now",
+            call_to_action_type="LEARN_MORE",
+            access_token="test_token",
+        )
+
+        creative_data = mock_api.call_args_list[1][0][2]
+
+        # Routed through asset_feed_spec, not the simple video_data path.
+        assert "asset_feed_spec" in creative_data
+        assert "video_data" not in creative_data.get("object_story_spec", {})
+
+        link_urls = creative_data["asset_feed_spec"]["link_urls"]
+        assert link_urls == [
+            {"website_url": "https://example.com/landing", "display_url": "brand.example"}
+        ]
+
+
+@pytest.mark.asyncio
+async def test_image_creative_with_display_url_uses_asset_feed_link_urls():
+    """display_url is also supported for image creatives via asset_feed_spec.link_urls."""
+
+    with patch('meta_ads_mcp.core.ads.make_api_request') as mock_api, \
+         patch('meta_ads_mcp.core.ads._discover_pages_for_account') as mock_discover:
+
+        mock_discover.return_value = {
+            "success": True,
+            "page_id": "123456789",
+            "page_name": "Test Page",
+        }
+
+        mock_api.side_effect = [
+            # 1) POST create creative
+            {"id": "creative_display_url_img"},
+            # 2) GET creative details
+            {"id": "creative_display_url_img", "name": "Display URL Image", "status": "ACTIVE"},
+        ]
+
+        result = await create_ad_creative(
+            account_id="act_123456",
+            image_hash="abc123",
+            name="Display URL Image Ad",
+            link_url="https://example.com/landing",
+            display_url="brand.example",
+            message="Body",
+            access_token="test_token",
+        )
+
+        creative_data = mock_api.call_args_list[0][0][2]
+        assert "asset_feed_spec" in creative_data
+        link_urls = creative_data["asset_feed_spec"]["link_urls"]
+        assert link_urls == [
+            {"website_url": "https://example.com/landing", "display_url": "brand.example"}
+        ]
+        assert creative_data["asset_feed_spec"]["images"] == [{"hash": "abc123"}]