### FBE Install API Response Example Source: https://developers.facebook.com/documentation/ads-commerce/commerce-platform/platforms/onboarding/fbe.md This is an example of the JSON response received when querying for FBE installs. It includes various IDs and the 'ig_shop' status. ```json { "data": [ { "business_manager_id": "0123456789", "commerce_merchant_settings_id": "0987654321", "onsite_eligible": true, "pixel_id": "000111", "profiles": [ "000111222" ], "ad_account_id": "000111222333", "catalog_id": "123456789", "pages": [ "1234567890" ], "instagram_profiles": [ "000111333" ], "ig_shop": { "status": "NOT_SUBMITTED" } } ] } ``` -------------------------------- ### Run Initial Ads CLI Commands Source: https://developers.facebook.com/documentation/ads-commerce/ads-ai-connectors/ads-cli/setup/get-started.md Examples of basic Ads CLI commands to get started with managing campaigns, insights, and pages. ```bash # List your ad campaigns meta ads campaign list ``` ```bash # Check performance for the last 30 days meta ads insights get --fields spend,impressions,ctr,cpc ``` ```bash # List your Business Pages (needed for creating ad creatives) meta ads page list ``` -------------------------------- ### Install Event Payload Example Source: https://developers.facebook.com/documentation/ads-commerce/conversions-api/app-events.md Example JSON payload for a MobileAppInstall event sent via the Conversions API. Includes user data and app-specific data. ```json { "data": [ { "event_name": "MobileAppInstall", "event_time": 1684389252, "action_source": "app", "user_data": { "client_ip_address": "2001:0db8:85a3:0000:0000:8a2e:0370:7334", "madid": "38400000-8cf0-11bd-b23e-10b96e40000d", "anon_id": "12345340-1234-3456-1234-123456789012" }, "app_data": { "advertiser_tracking_enabled": 1, "application_tracking_enabled": 1, "extinfo": [ "a2", "com.some.app", "771", "Version 7.7.1", "10.1.1", "OnePlus6", "en_US", "GMT-1", "TMobile", "1920", "1080", "2.00", "2", "128", "8", "USA/New York" ] } } ] } ``` -------------------------------- ### Sending Install Events Source: https://developers.facebook.com/documentation/ads-commerce/conversions-api/app-events.md This section provides an example payload for sending a MobileAppInstall event to the Conversions API. ```APIDOC ## POST /{API_VERSION}/{DATASET_ID}/events (Install Event) ### Description Sends a MobileAppInstall event to the Conversions API. ### Method POST ### Endpoint `https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}` ### Parameters #### Query Parameters - **access_token** (string) - Required - The token for authentication. #### Request Body - **data** (array) - Required - An array containing the install event object. - **event_name** (string) - Required - Must be "MobileAppInstall". - **event_time** (integer) - Required - The Unix timestamp of when the install occurred. - **action_source** (string) - Required - The source of the action, typically "app". - **user_data** (object) - Required - Contains user information. - **client_ip_address** (string) - Optional - The IP address of the user. - **madid** (string) - Optional - The Meta Advertiser ID. - **anon_id** (string) - Optional - An anonymous ID. - **app_data** (object) - Optional - Data related to the app. - **advertiser_tracking_enabled** (integer) - Optional - Indicates if advertiser tracking is enabled (1 or 0). - **application_tracking_enabled** (integer) - Optional - Indicates if application tracking is enabled (1 or 0). - **extinfo** (array of strings) - Optional - Extended information about the app and device. ### Request Example ```json { "data": [ { "event_name": "MobileAppInstall", "event_time": 1684389252, "action_source": "app", "user_data": { "client_ip_address": "2001:0db8:85a3:0000:0000:8a2e:0370:7334", "madid": "38400000-8cf0-11bd-b23e-10b96e40000d", "anon_id": "12345340-1234-3456-1234-123456789012" }, "app_data": { "advertiser_tracking_enabled": 1, "application_tracking_enabled": 1, "extinfo": [ "a2", "com.some.app", "771", "Version 7.7.1", "10.1.1", "OnePlus6", "en_US", "GMT-1", "TMobile", "1920", "1080", "2.00", "2", "128", "8", "USA/New York" ] } } ] } ``` ### Response #### Success Response (200) - The API will respond with a success status if the events are accepted for processing. Deduplication for app install events is handled by Meta, ensuring only one install is attributed in a 90-day window. #### Response Example (No specific example provided in the source) ``` -------------------------------- ### Check Setup Status from Seller Settings Source: https://developers.facebook.com/documentation/ads-commerce/commerce-platform/platforms/distribution/MPApprovalAPI.md After a seller requests to sell on Marketplace, this endpoint can be used to get information about the status of their request if there are any issues. ```APIDOC ## Check Setup Status from Seller Settings ### Description Retrieves the setup status for a seller's shop and Marketplace approval from their merchant settings. ### Method GET ### Endpoint https://graph.facebook.com/v25.0// ### Parameters #### Query Parameters - **fields** (string) - Required - Specifies the fields to retrieve. Use `cta,setup_status`. - **access_token** (string) - Required - Your valid access token. ### Response #### Success Response (200) - **shop_setup** ([shop_setup_status](#shop_setup_status)) - Status of the Page Shop. - **payment_setup** ([payment_setup_status](#payment_setup_status)) - Status of the seller payment details. - **marketplace_approval_status** ([marketplace_approval_status](#marketplace_approval_status)) - Status of seller's Marketplace approval. - **deals_setup** ([deals_setup](#deals_setup)) - Status of seller's Daily Deals allow list. - **marketplace_approval_status_details** ([marketplace_approval_status_details](#marketplace_approval_status_details)) - Details on the seller's approval status. ### Example Request (cURL) ```bash curl -X GET -G \ -d 'access_token=' \ https://graph.facebook.com/v25.0//?fields=cta,setup_status ``` ``` -------------------------------- ### Create Ad Set for Dynamic Creative (App Installs) Source: https://developers.facebook.com/documentation/ads-commerce/marketing-api/ad-creative/asset-feed-spec/dynamic-creative.md Example of creating an ad set optimized for app installs with Dynamic Creative enabled, including `asset_feed_spec` considerations. ```APIDOC ## Create Ad Set (App Installs) ### Description Creates an ad set for app installs with Dynamic Creative enabled. Requires `link_url` in `asset_feed_spec` to match `object_store_url` in `promoted_object`. ### Method POST ### Endpoint https://graph.facebook.com//act_AD_ACCOUNT_ID/adsets ### Parameters #### Form Parameters - **name** (string) - Required - The name of the ad set. - **campaign_id** (string) - Required - The ID of the parent campaign. - **optimization_goal** (string) - Required - The optimization goal, e.g., `APP_INSTALLS`. - **is_dynamic_creative** (boolean) - Required - Set to `true` to enable Dynamic Creative. - **billing_event** (string) - Optional - The billing event (e.g., `IMPRESSIONS`). - **is_autobid** (boolean) - Optional - Whether to use autobid. - **promoted_object** (object) - Required - Specifies the promoted object, including `object_store_url` and `application_id`. `object_store_url` must match `link_url` in `asset_feed_spec`. - **lifetime_budget** (string) - Optional - The lifetime budget for the ad set. - **end_time** (string) - Optional - The end time for the ad set (Unix timestamp). - **targeting** (object) - Optional - Targeting specifications, including `geo_locations`, `age_min`, `age_max`, `publisher_platforms`, and `user_os`. - **access_token** (string) - Required - Your API access token. ### Request Example ```curl curl \ -F "name=Dynamic Creative AdSet" \ -F "campaign_id=CAMPAIGN_ID" \ -F "optimization_goal=APP_INSTALLS" \ -F 'is_dynamic_creative=true' \ -F "billing_event=IMPRESSIONS" \ -F "is_autobid=true" \ -F "promoted_object={'object_store_url':'https://itunes.apple.com/us/app/facebook/id284882215','application_id':ADVERTISED_APP_ID}" // object_store_url must match what is provided in asset feed's link_urls \ -F "lifetime_budget=20000" \ -F "end_time=1461974400" \ -F "targeting={ 'geo_locations':{'countries':['US']}, 'age_min':18, 'age_max':24, 'publisher_platforms':['facebook', 'audience_network'], 'user_os':['ios'] }" \ -F "access_token=ACCESS_TOKEN" \ https://graph.facebook.com//act_AD_ACCOUNT_ID/adsets ``` ``` -------------------------------- ### Review Commerce Account Details Source: https://developers.facebook.com/documentation/ads-commerce/commerce-platform/platforms/onboarding/fbe.md Use this GET request to retrieve the setup status of a commerce account. Replace `{merchant-settings-id}` with the actual ID. ```bash curl -X GET -G \ -d 'access_token=' \ https://graph.facebook.com/{merchant-settings-id}/?fields=setup_status ``` -------------------------------- ### CHANGE_BID Example with Target Field and Limit Source: https://developers.facebook.com/documentation/ads-commerce/marketing-api/ad-rules/overview/change-spec.md This example shows how to scale bids daily based on a target cost per mobile app install, including a range filter to avoid minor proportional changes and limit the bid adjustments. ```APIDOC ## CHANGE_BID Rule Example with Target Field and Limit ### Description Creates a rule to scale ad set bids daily based on a target `cost_per_mobile_app_install` value, with a +/-10% range filter and limits on bid increases/decreases. ### Method POST ### Endpoint https://graph.facebook.com///adrules_library ### Parameters #### Request Body - **name** (string) - Required - The name of the rule. - **schedule_spec** (object) - Required - Specifies the rule's schedule. - **schedule_type** (string) - Required - Type of schedule, e.g., "DAILY". - **evaluation_spec** (object) - Required - Specifies the conditions for rule evaluation. - **evaluation_type** (string) - Required - Type of evaluation, e.g., "SCHEDULE". - **filters** (array) - Required - Filters to apply during evaluation. - **field** (string) - Required - The field to filter on (e.g., "id", "time_preset", "mobile_app_install", "cost_per_mobile_app_install"). - **value** (any) - Required - The value to filter by. - **operator** (string) - Required - The operator to use (e.g., "IN", "EQUAL", "GREATER_THAN", "NOT_IN_RANGE"). - **execution_spec** (object) - Required - Specifies the action to take when the rule is triggered. - **execution_type** (string) - Required - Type of execution, e.g., "CHANGE_BID". - **execution_options** (array) - Required - Options for execution. - **field** (string) - Required - The field to modify, e.g., "change_spec". - **value** (object) - Required - The specification for the change. - **amount** (number) - Required - The target value for the `target_field`. - **limit** (array) - Optional - Specifies a range for the bid (e.g., [lower_bound, upper_bound]). - **target_field** (string) - Optional - The Insights field to scale by (e.g., "cost_per_mobile_app_install"). - **operator** (string) - Required - The operator to use, e.g., "EQUAL". - **access_token** (string) - Required - User's access token. ### Request Example ```curl curl \ -F 'name=Test Change Bid Rule' \ -F 'schedule_spec={ "schedule_type": "DAILY" }' \ -F 'evaluation_spec={ "evaluation_type": "SCHEDULE", "filters": [ { "field": "id", "value": [123], "operator": "IN" }, { "field": "time_preset", "value": "LIFETIME", "operator": "EQUAL" }, { "field": "mobile_app_install", "value": 100, "operator": "GREATER_THAN" }, { "field": "cost_per_mobile_app_install", "value": [4.5, 5.5], "operator": "NOT_IN_RANGE" } ] }' \ -F 'execution_spec={ "execution_type": "CHANGE_BID", "execution_options": [ { "field": "change_spec", "value": { "amount": 5.0, "limit": [2.0, 10.0], "target_field": "cost_per_mobile_app_install" }, "operator": "EQUAL" }, ] }' \ -F "access_token=" \ https://graph.facebook.com///adrules_library ``` ``` -------------------------------- ### Callback URL after Commerce Setup Source: https://developers.facebook.com/documentation/ads-commerce/commerce-platform/platforms/onboarding/cmredirect.md This is an example of the URL your platform will be redirected to after the seller completes the Commerce Manager setup. The `cms_id` parameter will contain the ID of the newly created CommerceMerchantSettings object. ```url https://www.example.com/?cms_id=112358 ``` -------------------------------- ### Commerce Platform Launch Link Source: https://developers.facebook.com/documentation/ads-commerce/commerce-platform/platforms/onboarding/fbe.md This is an example launch link to direct sellers to the MBE management view for commerce setup. Replace `` and `` with your specific values. ```html https://www.facebook.com/facebook_business_extension/management/?app_id=&external_business_id=&tab=commerc ``` -------------------------------- ### Full Workflow: Set Up Conversion Tracking Source: https://developers.facebook.com/documentation/ads-commerce/ads-ai-connectors/ads-cli/datasets-and-catalogs A step-by-step guide to setting up conversion tracking. This involves creating and connecting a dataset (Pixel), optionally linking it to a catalog, and then creating a campaign, ad set, creative, and ad. ```shell # 1. Create a dataset (Pixel) meta ads dataset create --name "Website Pixel" ``` ```shell # 2. Connect the dataset to your ad account meta ads dataset connect --ad-account-id ``` ```shell # 3. (Optional) Connect to a catalog for product-level tracking meta ads dataset connect --catalog-id ``` ```shell # 4. Create a conversion ad campaign meta ads campaign create --name "Sales Campaign" --objective OUTCOME_SALES ``` ```shell # 5. Create a conversion ad set using a Pixel meta ads adset create --name "Purchase Optimization" \ --optimization-goal OFFSITE_CONVERSIONS \ --billing-event IMPRESSIONS \ --pixel-id \ --custom-event-type PURCHASE \ --targeting-countries US ``` ```shell # 6. Create an ad creative and ad meta ads creative create --name "Product Ad" --page-id \ --image ./product.jpg --body "Buy now!" \ --link-url https://example.com --call-to-action SHOP_NOW ``` ```shell meta ads ad create --name "Product Ad" \ --creative-id --pixel-id ``` -------------------------------- ### Check Onboarding Status from Seller Settings Source: https://developers.facebook.com/documentation/ads-commerce/commerce-platform/platforms/distribution/MPApprovalAPI.md Retrieve the setup status for a seller's Marketplace integration directly from their merchant settings. This is useful for understanding the current state of their Marketplace onboarding. ```html curl -X GET -G \ -d 'access_token=' \ https://graph.facebook.com/v25.0//?fields=cta,setup_status ``` -------------------------------- ### Example Checkout URL with Products and Coupon Source: https://developers.facebook.com/documentation/ads-commerce/commerce-platform/setup-checkout-url.md This URL includes both the 'products' parameter and an optional 'coupon' parameter, showing how to apply a discount code during the checkout process. ```url https://www.example.com/checkout?products=12345%3A3%2C23456%3A1&coupon=SUMMERSALE20 ``` -------------------------------- ### Create Ad with Product Video Enabled Source: https://developers.facebook.com/documentation/ads-commerce/marketing-api/advantage-catalog-ads/allow-product-video This example demonstrates how to create an ad object and enable product videos by setting `media_type_automation` to `OPT_IN` within the `creative` object's `degrees_of_freedom_spec`. ```APIDOC ## Create Ad with Product Video Enabled ### Description This endpoint allows you to create an ad object and enable the use of product videos from your catalog. By setting `media_type_automation.enroll_status` to `OPT_IN` within the `creative` object's `degrees_of_freedom_spec`, you allow Advantage+ catalog ads to deliver product videos by default. This setting is applicable for carousel, collection, and single image formats. ### Method POST ### Endpoint `https://graph.facebook.com/v25.0/act_/ads` ### Parameters #### Request Body - **adset_id** (string) - Required - The ID of the ad set. - **creative** (object) - Required - The creative object for the ad. - **name** (string) - Required - The name of the ad creative. - **object_story_spec** (object) - Required - Specifies the story format for the ad. - **degrees_of_freedom_spec** (object) - Optional - Allows customization of creative features. - **creative_features_spec** (object) - Required if `degrees_of_freedom_spec` is used. - **media_type_automation** (object) - Required if `creative_features_spec` is used. - **enroll_status** (string) - Required - Set to `OPT_IN` to enable product videos. - **product_set_id** (string) - Required - The ID of the product set to be used for the ad. ### Request Example ```curl curl -X POST \ -F 'adset_id=' \ -F 'creative={ "name": "Product video ad creative", "object_story_spec": { ... }, "degrees_of_freedom_spec": { "creative_features_spec": { "media_type_automation": { "enroll_status": "OPT_IN" } } }, "product_set_id": "" }' \ https://graph.facebook.com/v25.0/act_/ads ``` ``` -------------------------------- ### Full Ad Object Example Source: https://developers.facebook.com/documentation/ads-commerce/ccco This is a complete example of an ad object, including name, adset_id, creative, status, and multiple tracking specs for pixel, app install, and app events. ```json { "name": "sample ad" "adset_id": "6170648652866", "creative": { "creative_id": creative_id, } "status": "PAUSED", "tracking_specs": [ { "action.type": ["offsite_conversion"], "fb_pixel": [pixel_id] } { "action.type": ["mobile_app_install"], "application": [application_id] } { "action.type": ["app_custom_event"], "application": [application_id] } ] } ``` -------------------------------- ### Ad Set Create Example with LOWEST_COST_WITH_MIN_ROAS bid strategy Source: https://developers.facebook.com/documentation/ads-commerce/marketing-api/advantage-shopping-campaigns.md Example of creating an ad set using the LOWEST_COST_WITH_MIN_ROAS bid strategy. ```APIDOC ## Ad Set Create Example with LOWEST_COST_WITH_MIN_ROAS bid strategy ### Description Creates a new ad set specifying a `LOWEST_COST_WITH_MIN_ROAS` bid strategy. ### Method POST ### Endpoint https://graph.facebook.com//act_/adsets ### Parameters #### Request Body - **name** (string) - Required - The name of the ad set. - **optimization_goal** (string) - Required - The optimization goal for the ad set (e.g., OFFSITE_CONVERSIONS). - **billing_event** (string) - Required - The billing event type (e.g., IMPRESSIONS). - **bid_strategy** (string) - Required - The bid strategy, set to `LOWEST_COST_WITH_MIN_ROAS`. - **bid_constraints** (JSON object) - Required when `bid_strategy` is `LOWEST_COST_WITH_MIN_ROAS` - Constraints for the bid strategy, e.g., `{"roas_average_floor": 1000}`. - **daily_budget** (number) - Required - The daily budget for the ad set. - **campaign_id** (string) - Required - The ID of the campaign this ad set belongs to. - **targeting** (JSON object) - Required - Targeting criteria, e.g., `{"geo_locations":{"countries":["US"]}}`. - **status** (string) - Optional - The status of the ad set (e.g., PAUSED). - **access_token** (string) - Required - User's access token. ### Request Example ```curl curl \ -F 'name=My Ad Set' \ -F 'optimization_goal=OFFSITE_CONVERSIONS' \ -F 'billing_event=IMPRESSIONS' \ -F 'bid_strategy=LOWEST_COST_WITH_MIN_ROAS' \ -F 'bid_constraints={"roas_average_floor": 1000}' \ -F 'daily_budget=1000' \ -F 'campaign_id=' \ -F 'targeting={"geo_locations":{"countries":["US"]}}' \ -F 'status=PAUSED' \ -F 'access_token=' \ https://graph.facebook.com//act_/adsets ``` ``` -------------------------------- ### Ad Set Create Example Source: https://developers.facebook.com/documentation/ads-commerce/marketing-api/advantage-shopping-campaigns.md Example of creating a new ad set with basic parameters. ```APIDOC ## Ad Set Create Example ### Description Creates a new ad set with specified parameters. ### Method POST ### Endpoint https://graph.facebook.com/v25.0/act_/adsets ### Parameters #### Request Body - **name** (string) - Required - The name of the ad set. - **campaign_id** (string) - Required - The ID of the campaign this ad set belongs to. - **promoted_object** (JSON object) - Required - Object containing details of the promoted item, e.g., `{"pixel_id": "", "CUSTOM_EVENT_TYPE": "PURCHASE"}`. - **daily_budget** (number) - Optional - The daily budget for the ad set. - **existing_customer_budget_percentage** (number) - Optional - Percentage of budget to be spent on existing customers (0-100). - **billing_event** (string) - Required - The billing event type (e.g., IMPRESSIONS). - **targeting** (JSON object) - Required - Targeting criteria, e.g., `{"geo_locations": {"countries": ["US"]}}`. - **access_token** (string) - Required - User's access token. ### Request Example ```curl curl -X POST \ -F 'name=Advantage+ Shopping Sample Ad Set' \ -F 'campaign_id=' \ -F 'promoted_object={ "pixel_id": "", "CUSTOM_EVENT_TYPE": "PURCHASE" }' \ -F 'daily_budget=' \ -F 'existing_customer_budget_percentage=' \ -F 'billing_event=IMPRESSIONS' \ -F 'targeting={"geo_locations": {"countries": ["US"]}}' \ -F 'access_token=' \ https://graph.facebook.com/v25.0/act_/adsets ``` ### Response #### Success Response (200) - **id** (string) - The ID of the created ad set. #### Response Example ```json { "id": "" } ``` ``` -------------------------------- ### Get Upload Sessions Request Source: https://developers.facebook.com/documentation/ads-commerce/catalog/guides/generic-feed-files-api Example cURL command to fetch upload sessions for a given feed ID. ```bash curl -X GET -G \ -d 'access_token=' \ https://graph.facebook.com/{GENERIC_FEED_ID}/uploads ``` -------------------------------- ### Install Conversions API Gateway Source: https://developers.facebook.com/documentation/ads-commerce/gateway-products/gateway-gcp/create-instance-agencies-partners.md Use this command in GCP Cloud Shell to initiate the installation of the Conversions API Gateway. Ensure you have administrator privileges and have opened an ephemeral Cloud Shell session. ```bash bash <(curl -sL https://storage.googleapis.com/capig-prod-public-release/install-cloudrun.sh) ``` -------------------------------- ### Get Event Statistics Source: https://developers.facebook.com/documentation/ads-commerce/catalog/guides/cat-signals-quality Query the Event API to get aggregate statistics about matched and unmatched events received from different pixels, apps, and devices linked to your catalog. This provides insights into potential issues with your pixel or app installation. ```APIDOC ## GET /v25.0/{PRODUCT_CATALOG_ID}/event_stats ### Description Retrieves aggregate statistics about matched and unmatched pixel and app events for a given product catalog. This data helps identify issues with pixel or app installations by showing event performance over the last month. ### Method GET ### Endpoint https://graph.facebook.com/v25.0/{PRODUCT_CATALOG_ID}/event_stats ### Parameters #### Query Parameters - **access_token** (string) - Required - Your Facebook API access token. ### Request Example ```html curl -X GET \ -d 'access_token=' https://graph.facebook.com/v25.0//event_stats ``` ### Response #### Success Response (200) Returns an array of elements, one per event type, source, and date within the last month. Each element contains counts for matched, unmatched, and other catalog-matched content IDs, both total and unique. - **data** (array) - Contains event statistics objects. - **date_start** (string) - The start date for the statistics. - **date_stop** (string) - The end date for the statistics. - **event** (string) - The type of event (e.g., 'AddToCart', 'ViewContent'). - **event_source** (object) - Information about the source of the event. - **id** (string) - The ID of the pixel or app. - **source_type** (string) - The type of the source ('PIXEL' or 'APP'). - **total_matched_content_ids** (integer) - Total number of content IDs from received events that matched to an item in the catalog (not de-duplicated). - **total_content_ids_matched_other_catalogs** (integer) - Total number of content IDs from received events that matched to an item in another catalog (not de-duplicated). - **total_unmatched_content_ids** (integer) - Total number of content IDs from received events that didn't match an item in the catalog (not de-duplicated). - **unique_matched_content_ids** (integer) - Number of unique content IDs from received events that matched to an item in the catalog. - **unique_content_ids_matched_other_catalogs** (integer) - Number of unique content IDs from received events that matched to an item in another catalog. - **unique_unmatched_content_ids** (integer) - Number of unique content IDs from received events that didn't match an item in the catalog. #### Response Example ```json { "data": [ { "date_start": "2017-03-16", "date_stop": "2017-03-16", "event": "AddToCart", "event_source": { "id": "", "source_type": "PIXEL" }, "total_matched_content_ids": 1086, "total_content_ids_matched_other_catalogs": 10024, "total_unmatched_content_ids": 13024, "unique_matched_content_ids": 285, "unique_content_ids_matched_other_catalogs": 102, "unique_unmatched_content_ids": 2132 } ] } ``` ``` -------------------------------- ### Read Ad Group Leads (HTTP) Source: https://developers.facebook.com/documentation/ads-commerce/graph-api/reference/adgroup/leads.md Example of an HTTP GET request to retrieve leads for a specific ad group. ```http GET /v25.0/{adgroup-id}/leads HTTP/1.1 Host: graph.facebook.com ``` -------------------------------- ### Create Ad Set for Offsite Conversions and Impression Billing Source: https://developers.facebook.com/documentation/ads-commerce/marketing-api/advantage-catalog-ads/get-started Use this example to create an ad set optimized for offsite conversions and billed on impressions. Ensure you specify the `product_set_id` in `promoted_object`. ```bash curl \ -F 'name=Product Catalog Sales Adset' \ -F 'bid_amount=3000' \ -F 'billing_event=IMPRESSIONS' \ -F 'optimization_goal=OFFSITE_CONVERSIONS' \ -F 'daily_budget=15000' \ -F 'campaign_id=' \ -F 'targeting={ "geo_locations": {"countries":["US"]}, "dynamic_audience_ids": [""] }' \ -F 'promoted_object={"product_set_id":""}' \ -F 'status=PAUSED' \ -F 'access_token=' \ https://graph.facebook.com/v25.0/act_/adsets ``` -------------------------------- ### Ad Set Create Example with COST_CAP bid strategy Source: https://developers.facebook.com/documentation/ads-commerce/marketing-api/advantage-shopping-campaigns.md Example of creating an ad set using the COST_CAP bid strategy. ```APIDOC ## Ad Set Create Example with COST_CAP bid strategy ### Description Creates a new ad set specifying a `COST_CAP` bid strategy. ### Method POST ### Endpoint https://graph.facebook.com//act_/adsets ### Parameters #### Request Body - **name** (string) - Required - The name of the ad set. - **optimization_goal** (string) - Required - The optimization goal for the ad set (e.g., OFFSITE_CONVERSIONS). - **billing_event** (string) - Required - The billing event type (e.g., IMPRESSIONS). - **bid_strategy** (string) - Required - The bid strategy, set to `COST_CAP`. - **bid_amount** (number) - Required when `bid_strategy` is `COST_CAP` - The bid cap amount. - **daily_budget** (number) - Required - The daily budget for the ad set. - **campaign_id** (string) - Required - The ID of the campaign this ad set belongs to. - **targeting** (JSON object) - Required - Targeting criteria, e.g., `{"geo_locations":{"countries":["US"]}}`. - **status** (string) - Optional - The status of the ad set (e.g., PAUSED). - **access_token** (string) - Required - User's access token. ### Request Example ```curl curl \ -F 'name=My Ad Set' \ -F 'optimization_goal=OFFSITE_CONVERSIONS' \ -F 'billing_event=IMPRESSIONS' \ -F 'bid_strategy=COST_CAP' \ -F 'bid_amount=200' \ -F 'daily_budget=1000' \ -F 'campaign_id=' \ -F 'targeting={"geo_locations":{"countries":["US"]}}' \ -F 'status=PAUSED' \ -F 'access_token=' \ https://graph.facebook.com//act_/adsets ``` ``` -------------------------------- ### Commerce Account Status Response Source: https://developers.facebook.com/documentation/ads-commerce/commerce-platform/platforms/onboarding/fbe.md This is an example response when querying commerce account details. It indicates the setup and review status of the account. ```json { "data": [ { "shop_setup": "SETUP", "payment_setup": "SETUP", "review_status": { "status": "REJECTED", "reasons": [ { "code": "UNKNOWN", "message": "Your account is not eligible for Facebook Shops at this time.", "help_url": "https://www.facebook.com/help/contact/481136396104354" } ] } } ] } ``` -------------------------------- ### Create Ad with Default Advantage+ Creative for Catalog Source: https://developers.facebook.com/documentation/ads-commerce/marketing-api/advantage-creative-for-catalog.md This example demonstrates how to create an ad using Advantage+ creative for catalog with default settings, where the cover media defaults to an Advantage catalog video. ```APIDOC ## POST /v/act_/ads ### Description Creates an ad with Advantage+ creative for catalog, utilizing default settings for cover media. ### Method POST ### Endpoint https://graph.facebook.com/v/act_/ads ### Parameters #### Form Data - **name** (string) - Required - The name of the ad. - **adset_id** (string) - Required - The ID of the ad set. - **creative** (object) - Required - The creative specification for the ad. - **name** (string) - Required - The name of the creative. - **product_set_id** (string) - Required - The ID of the product set. - **object_type** (string) - Required - The object type, typically 'SHARE'. - **object_story_spec** (object) - Required - Specifies the story details. - **page_id** (string) - Required - The ID of the Facebook page. - **template_data** (object) - Required - Template data for the story. - **multi_share_end_card** (string) - Required - Set to 'true' for multi-share end card. - **name** (string) - Required - The name of the product. - **link** (string) - Required - The landing page URL. - **message** (string) - Required - The ad copy message. - **call_to_action** (object) - Required - Call to action details. - **type** (string) - Required - The type of call to action, e.g., 'SHOP_NOW'. - **asset_feed_spec** (object) - Required - Specifies the asset feed. - **optimization_type** (string) - Required - Optimization type, e.g., 'FORMAT_AUTOMATION'. - **ad_formats** (array) - Required - List of ad formats, e.g., ['CAROUSEL', 'COLLECTION']. - **descriptions** (array) - Optional - List of descriptions. - **url_tags** (string) - Required - URL tags for tracking. - **tracking_specs** (array) - Required - Tracking specifications. - **action.type** (string) - Required - The type of action to track. - **fb_pixel** (string) - Required - The Facebook Pixel ID. ### Request Example ```json { "name": "Advantage+ creative for catalog test", "adset_id": "", "creative": { "name": "Creative for Advantage+ creative for catalog test", "product_set_id": "", "object_type": "SHARE", "object_story_spec": { "page_id": "", "template_data": { "multi_share_end_card": "true", "name": "{{product.name}}", "link": "", "message": "", "call_to_action": {"type": "SHOP_NOW"} } }, "asset_feed_spec": { "optimization_type": "FORMAT_AUTOMATION", "ad_formats": ["CAROUSEL", "COLLECTION"], "descriptions": [{"text": "{{product.brand}}", "From {{product.current_price}}", ...}] } }, "url_tags": "", "tracking_specs": [{"action.type": "offsite_conversion", "fb_pixel": }] } ``` ### Response #### Success Response (200) - **id** (string) - The ID of the created ad. #### Response Example ```json { "id": "" } ``` ``` -------------------------------- ### Get Account-Level Metrics Source: https://developers.facebook.com/documentation/ads-commerce/ads-ai-connectors/ads-cli/insights.md Retrieve default account-level metrics for the last 30 days. This is the basic command to start querying insights. ```bash meta ads insights get ``` -------------------------------- ### Create Ad Creative with Product Video Enabled Source: https://developers.facebook.com/documentation/ads-commerce/marketing-api/advantage-catalog-ads/allow-product-video This example shows how to create an ad creative object and enable product videos by setting `media_type_automation` to `OPT_IN` within the `degrees_of_freedom_spec`. ```APIDOC ## Create Ad Creative with Product Video Enabled ### Description This endpoint allows you to create an ad creative object and enable the use of product videos from your catalog. By setting `media_type_automation.enroll_status` to `OPT_IN` within the `degrees_of_freedom_spec`, you allow Advantage+ catalog ads to deliver product videos by default. This setting is applicable for carousel, collection, and single image formats. ### Method POST ### Endpoint `https://graph.facebook.com/v25.0/act_/adcreatives` ### Parameters #### Request Body - **name** (string) - Required - The name of the ad creative. - **object_story_spec** (object) - Required - Specifies the story format for the ad. - **degrees_of_freedom_spec** (object) - Optional - Allows customization of creative features. - **creative_features_spec** (object) - Required if `degrees_of_freedom_spec` is used. - **media_type_automation** (object) - Required if `creative_features_spec` is used. - **enroll_status** (string) - Required - Set to `OPT_IN` to enable product videos. - **product_set_id** (string) - Required - The ID of the product set to be used for the ad. ### Request Example ```curl curl -X POST \ -F 'name=Product video ad creative' \ -F 'object_story_spec={ ... }' \ -F 'degrees_of_freedom_spec={ "creative_features_spec": { "media_type_automation": { "enroll_status": "OPT_IN" } } }' \ -F 'product_set_id=' \ https://graph.facebook.com/v25.0/act_/adcreatives ``` ``` -------------------------------- ### Full Ad Creative Workflow Example Source: https://developers.facebook.com/documentation/ads-commerce/ads-ai-connectors/ads-cli/ad-creatives This example demonstrates a complete workflow: finding a Business Page ID, creating an ad creative with various parameters, creating an ad using the creative ID, and finally activating the ad. ```bash # 1. Find your Business Page ID meta ads page list ``` ```bash # 2. Create an ad creative meta ads creative create --name "Launch Ad" \ --page-id \ --image ./launch-banner.jpg \ --body "Our new product is here!" \ --title "Just Launched" \ --link-url https://example.com/launch \ --call-to-action SHOP_NOW ``` ```bash # 3. Create an ad with the returned ad creative ID meta ads ad create --name "Launch Ad - US" --creative-id ``` ```bash # 4. Activate the ad with the returned ad ID meta ads ad update --status ACTIVE ``` -------------------------------- ### Get Upload Sessions Response Source: https://developers.facebook.com/documentation/ads-commerce/catalog/guides/generic-feed-files-api Sample JSON response containing a list of upload sessions, each with an ID, start time, and end time. ```json { "data": [ { "id": "{UPLOAD_SESSION_ID}}", "start_time": "2019-07-15T12:38:36+0000", "end_time": "2019-07-15T12:38:47+0000" }, { "id": "{UPLOAD_SESSION_ID}}", "start_time": "2019-07-13T12:31:36+0000", "end_time": "2019-07-13T12:32:47+0000" }, { "id": "{UPLOAD_SESSION_ID}}", "start_time": "2019-07-12T22:14:00+0000", "end_time": "2019-07-12T23:38:47+0000" } ] } ``` -------------------------------- ### Create a Product Catalog Source: https://developers.facebook.com/documentation/ads-commerce/ads-ai-connectors/ads-cli/datasets-and-catalogs Creates a new product catalog. Specify a name and optionally a vertical type for the catalog. ```shell meta ads catalog create --name "My Product Catalog" ``` ```shell meta ads catalog create --name "Hotel Inventory" --vertical hotels ``` -------------------------------- ### Read Ad Group Leads (cURL) Source: https://developers.facebook.com/documentation/ads-commerce/graph-api/reference/adgroup/leads.md Example using cURL to make a GET request for ad group leads, including an access token. ```bash curl -X GET -G \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v25.0/{adgroup-id}/leads ``` -------------------------------- ### Get Threads Ads Insights with Breakdowns Source: https://developers.facebook.com/documentation/ads-commerce/marketing-api/ad-creative/threads-ads/insights.md Add `breakdowns=publisher_platform, platform_position` to see insights for Instagram, Facebook, and Threads placements separately. This example requests impressions. ```curl curl -X GET \ -d 'access_token=' -d 'fields=impressions' -d 'breakdowns=publisher_platform, platform_position' \ "https://graph.facebook.com/v25.0//insights" ``` -------------------------------- ### Get Account Sample Response Source: https://developers.facebook.com/documentation/ads-commerce/gateway-products/gateway-control-plane-api/account-management.md Example JSON response when successfully fetching an advertiser account. It includes the account ID, name, and associated user information. ```json { "data": { "tenant": { "id": "wW58k7FQ", "name": "Test Account", "users": [ { "id": "992bc489-a799-4374-8933-0109eed60e3d", "email": "tempuser@test.com", "roles": [ { "name": "advertiser-manage-wW58k7FQ", "displayName": "manage" } ] } ] } } } ``` -------------------------------- ### TSV Feed with Metadata Tags Source: https://developers.facebook.com/documentation/ads-commerce/catalog/guides/metadata-tags This example shows how to include `ref_application_id` and `ref_asset_id` as comments at the top of a TSV feed file. This is useful for initial feed setup. ```text # ref_application_id # ref_asset_id id title ios_url ios_app_store_id ios_app_name android_url android_package android_app_name windows_phone_url windows_phone_app_id windows_phone_app_name description google_product_category product_type link image_link condition availability price sale_price sale_price_effective_date gtin brand mpn item_group_id gender age_group color size shipping custom_label_0 DB_1 Dog Bowl In Blue example-ios://electronic/db_1 123 Electronic Example iOS example-android://electronic/db_1 com.electronic.example Electronic Example Android example-windows://electronic/db_1 64ec0d1b-5b3b-4c77-a86b-5e12d465edc0 Electronic Example Windows Solid plastic Dog Bowl in marine blue color Animals > Pet Supplies Bowls & Dining > Food & Water Bowls http://www.example.com/bowls/db-1.html https://www.facebook.com/images/product_image_template.png?id=1 new in stock 9.99 GBP Example DB_GROUP_1 UK::Standard:9.95 GBP "Made in Waterford, IE" ... ``` -------------------------------- ### Check Onboarding Status from a Page Source: https://developers.facebook.com/documentation/ads-commerce/commerce-platform/platforms/distribution/MPApprovalAPI.md Check the Marketplace setup status associated with a specific Facebook Page. This endpoint provides an alternative way to monitor a seller's onboarding progress. ```html curl -X GET -G \ -d 'access_token=' \ https://graph.facebook.com/v25.0//shop_setup_status ``` -------------------------------- ### Ad Creation with Multiple Tracking Specs Source: https://developers.facebook.com/documentation/ads-commerce/marketing-api/advantage-shopping-campaigns/cross-channel-conversion.md Example of creating an ad with a specified creative and multiple tracking specifications including pixel, app install, and app event tracking. ```json { "name": "sample ad" "adset_id": "6170648652866", "creative": { "creative_id": , } "status": "PAUSED", "tracking_specs": [ { "action.type": ["offsite_conversion"], "fb_pixel": [] } { "action.type": ["mobile_app_install"], "application": [] } { "action.type": ["app_custom_event"], "application": [] } ] } ``` -------------------------------- ### Read Ad Group Leads (JavaScript SDK) Source: https://developers.facebook.com/documentation/ads-commerce/graph-api/reference/adgroup/leads.md Example using the JavaScript SDK to make a GET request for ad group leads. Includes a callback for handling the response. ```javascript /* make the API call */ FB.api( "/{adgroup-id}/leads", function (response) { if (response && !response.error) { /* handle the result */ } } ); ```