Connect Meta Ads

Once connected, StoreClaw can read and analyze your authorized Facebook and Instagram advertising data, including ad accounts, campaigns, ad sets, ads, spend, impressions, clicks, conversions, and ROAS. It can also help diagnose performance issues, investigate anomalies, and recommend optimizations.

In the current version, the Meta Ads connector is managed through the corresponding plugin. Install the Meta Ads plugin first, then connect your ad account with a Meta system user access token.

Recommended Workflows

• Review performance at the ad account, campaign, ad set, and ad levels.
• Analyze spend, impressions, reach, CTR, CPC, CPM, conversions, and ROAS.
• Compare campaigns, audiences, and creatives to identify unusual changes.
• Generate ad copy, creative directions, and budget optimization recommendations.

After connecting, you can use StoreClaw to:

• Discover Meta ad accounts and query advertising data.
• Analyze campaign, ad set, and ad performance.
• Compare Facebook and Instagram ad creatives.
• Improve ad copy and develop A/B testing ideas.
• Investigate underperforming ads, abnormal spend, and conversion issues.

Security Note: The current StoreClaw Meta Ads plugin supports asset discovery, advertising data retrieval, offline report analysis, diagnostics, and read-only planning. It cannot create, edit, pause, or delete ads, and it does not change budgets, bids, or audiences.

Before You Begin

Before connecting, make sure that the following requirements are met. Meta labels may vary slightly by interface language and rollout version; use the English menu paths in this guide to identify the same controls.

• You can sign in to StoreClaw.
• You are signed in to Facebook, Meta Business Suite, and Meta for Developers.
• Your Facebook account has full control of the target business portfolio.
• The target business portfolio contains an active Meta ad account.
• The system user has access to the target ad account.
• You can create a Meta app and generate a system user access token.

Security Note: Treat the access token like a password. Do not paste it into StoreClaw chats, messaging apps, email, support tickets, or public documents. Enter it only in the StoreClaw Meta Ads connection form.

Connection Overview

Connecting Meta Ads usually involves four stages:

1. Create and configure a Meta app.
2. Create a system user and assign the target ad account.
3. Generate an access token for the system user.
4. Enter the token in StoreClaw and complete the connection.

Stage 1: Create a Meta App

Step 1: Open the App Management Page

1. Go to https://business.facebook.com/settings/ and select the business portfolio you want to connect.
2. In the left navigation, go to Accounts → Apps.
3. Click Add in the upper-right corner or in the center of the page.

Step 2: Create a New App ID

Click Add, then select Create a new App ID in the dialog.

Step 3: Enter the App Details

1. Enter a descriptive app name, such as StoreClaw Meta Ads.
2. Enter a monitored email address that will remain active.
3. Click Next.

Step 4: Select App Use Cases

For the StoreClaw Meta Ads connection, select at least:

• Create and manage ads with the Marketing API.
• Measure ad performance data with the Marketing API.

Select additional use cases—such as leads, mobile app ads, Audience Network, or Catalog API—only when your workflow requires them.

Step 5: Link the Business Portfolio

1. Select the business portfolio that owns the target ad account.
2. Confirm the app name, contact email, use cases, and business portfolio.
3. Review and accept the Meta Platform Terms and Developer Policies, then finish creating the app.

Stage 2: Create a System User and Assign the Ad Account

Step 1: Create a System User

1. Return to Meta Business Settings.
2. In the left navigation, go to Users → System users.
3. Click Add.
4. Enter a system user name, such as StoreClaw System User.
5. Select Admin or another system user role with sufficient permissions.

If the Add button is unavailable, check:

• Whether your Meta developer account registration is complete.
• Whether a Meta app has been added to the current business portfolio.
• Whether your Facebook account has full control of the business portfolio.
• Whether Meta requires two-factor authentication or business verification.

Step 2: Assign the Meta App to the System User

1. Select the system user you just created from the system user list.
2. Click the ... button in the upper-right corner, then select Assign assets.
3. Select Apps under Select asset type.
4. Select the Meta app created in Stage 1.
5. Enable Manage app under Full access.
6. Click Assign assets to finish.
7. Return to the system user details page and confirm that the Meta app is now assigned.

Important: If the Meta app is not assigned to the system user, you may not be able to select it when generating a token later.

Step 3: Assign the Ad Account to the System User

1. Select the system user you just created.
2. Click Add assets.
3. Select Ad accounts.
4. Select the ad account you want to connect to StoreClaw.
5. Enable Manage campaigns or Full control as required by the current connection form so the system user can generate a token that includes ads_management. The current StoreClaw Meta Ads plugin remains read-only and does not perform ad write operations.
6. Save the asset assignment.
7. Return to the system user details page and confirm that the ad account appears under Assigned assets.

Important: The ad data a token can access depends on which assets are assigned to the system user. Even if the token is generated successfully, StoreClaw cannot read an ad account unless it is assigned to the system user.

Stage 3: Generate a Meta Access Token

Step 1: Click Generate Token

After confirming that the ad account is assigned, click Generate token in the upper-right corner of the system user details page.

Step 2: Select the App

In the Generate token wizard, select the Meta app created in Stage 1 and linked to the same business portfolio, then click Next.

If no app appears in the dropdown, confirm:

• The app was created successfully.
• The app is linked to the current business portfolio.
• The selected system user and app belong to the same business portfolio.

Step 3: Set the Token Expiration

If Meta offers an expiration option, select Never or Never expire to prevent the StoreClaw connection from breaking when the token expires.

If Meta only allows a limited validity period, choose the longest available period and regenerate the token before it expires.

Step 4: Select Permissions

The StoreClaw connection form requires at least:

Permission	Purpose
ads_read	Read ad accounts, campaigns, ad sets, ads, and performance data
ads_management	A permission scope required by the current connection form for Meta authorization and asset access. The current StoreClaw version does not use it to create or modify ads

Permission and Product Capability Note: A token that includes ads_management is permitted by Meta to use that scope; it does not mean StoreClaw has implemented write operations. The current https://www.storeclaw.ai/app/plugins/metaads supports asset discovery, data queries, offline report analysis, diagnostics, and read-only planning.

Depending on your workflow, you may also select permissions related to Pages, Instagram, or catalogs:

• business_management
• read_insights
• pages_show_list
• pages_read_engagement
• pages_manage_ads
• instagram_basic
• catalog_management

After selecting permissions, click Generate token.

Step 5: Copy and Store the Token

After the token is generated:

1. Click Copy next to the token.
2. Store it temporarily in a secure password manager.
3. Do not rely on returning to the page later—Meta may not display the full token again.
4. Do not take a screenshot, forward the token, or share it with anyone.

Security Note: If a token appears in a screenshot, chat log, or public document, return to the system user page immediately, click Revoke token, and generate a new one.

Stage 4: Complete the Connection in StoreClaw

Step 1: Open the Meta Ads Connector

1. Sign in to https://www.storeclaw.ai/.
2. Click Plugins in the left navigation.
3. Find Meta Ads under Marketing.
4. Click + on the plugin card, or open the plugin details page and click Install plugin.
5. In the connector section, find Meta Ads, start the connection, and select Continue with Meta Ads.

Step 2: Enter the Access Token

Paste the complete token into the Access Token field on the connection page.

Click Connect Account.

Step 3: Confirm the Connection

After the connection succeeds, you are returned to StoreClaw. On the Meta Ads plugin details page, confirm that the connector status is Connected.

To test the connection, start a new StoreClaw chat and ask:

List the ad accounts accessible with the current Meta token, and summarize spend, impressions, clicks, CTR, CPC, conversions, and ROAS for the last 7 days.

If StoreClaw returns the expected ad account and metrics, the Meta Ads connection is ready.

Troubleshooting

Cannot Register a Meta Developer Account

If you do not receive an SMS verification code during developer registration:

• Verify the country code and phone number format.
• Check spam or blocked SMS folders and security-app filters.
• Avoid repeatedly requesting another code, which may trigger rate limits.
• Ask your mobile carrier whether it supports international business SMS messages.
• If necessary, try a valid number from another carrier.

The Add System User Button Is Unavailable

Confirm that your Meta developer account registration is complete, the business portfolio contains an app, and your account has full control. Meta may also require two-factor authentication or business verification.

No App Appears When Generating a Token

Confirm that the app is linked to the current business portfolio. Creating the app in Meta for Developers without linking it to the business portfolio may prevent the system user from selecting it.

Token Generated Successfully, But StoreClaw Cannot Read the Ad Account

The system user usually does not have access to the target ad account. Return to System users → Assigned assets and confirm that the ad account is assigned with the permissions required to read or manage ads.

StoreClaw Reports an Invalid Token or Insufficient Permissions

Check the following:

• The token was copied in full and does not contain leading or trailing spaces or line breaks.
• The token has not expired or been revoked.
• The token includes at least ads_read and ads_management.
• The system user still has access to the target ad account.
• The app selected when generating the token is still active.

Can Connect an Owned Ad Account, But Not a Client Ad Account

Basic access and the relevant permissions are usually sufficient for ad accounts owned by the current business. Accessing an ad account owned by another company or client may require business verification, app review, and a higher Marketing API access tier.

FAQ