Ads

See all your customers' Meta Ads in one call via API

Three routes under /merchants/ads give you the overview of campaigns, ad sets and ads across all your customers, with just the merchant token and no x-customer-token. You monitor the whole base in one call, without walking customer by customer and without implementing the Meta API.

The request

GET /api/merchants/ads/campaigns?customer=<customer uuid>&effective_status=disapproved&per_page=50
Authorization: Bearer <merchant token>

What you can do

  • List campaigns, ad sets and ads of all customers with GET /merchants/ads/campaigns, /merchants/ads/adsets and /merchants/ads.
  • Narrow to one customer with customer or to one account with customer_integration.
  • Filter by status and by effective_status, such as disapproved, with_issues or pending_review.
  • Identify each object's owner through customer_uuid and customer_integration_uuid.
  • Include deleted ones with include_deleted=true and paginate with page and per_page.

Rules and limits

  • These routes use only Authorization: Bearer. They take no x-customer-token, and customer and customer_integration are filters, never credentials.
  • They show what Connect stores: what it created or already wrote in the accounts. An account with older campaigns only shows up after the first write through Connect.
  • The data is the last known state, with synced_at. refresh=true re-reads the response's objects, but requires customer_integration.
  • The customer and connection you pass must belong to the token's merchant. With both, the connection must belong to that customer.
  • per_page goes from 1 to 100 (default 15) and the response is {data, links, meta}.

Main fields

FieldTypeRequiredDescription
customerstringNoThe uuid of one of your customers. Without it, the response includes all customers.
customer_integrationstringNoThe uuid of a connection of one of your customers, to narrow to one account. With customer, the connection must belong to that customer.
statusstringNoFilters by the last known status: active or paused.
effective_statusstringNoFilters by the last effective status seen, such as pending_review, disapproved or with_issues.
refreshbooleanNoRe-reads the response's objects from the platform and updates Connect. Requires customer_integration.
include_deletedbooleanNoIncludes deleted objects, with deleted_at.
per_pageintegerNoItems per page, from 1 to 100. The default is 15.
customer_uuidstringNoIn the response: the customer that owns each object's account.

Who it is for

  • Monitor rejected ads across the base

    A traffic SaaS lists with effective_status=disapproved and notifies each affected customer, without querying account by account.

  • Manager view at an agency

    An agency sees every customer's active campaigns on one screen, filtering by customer when it needs to dig in.

  • Support AI agent

    An agent gets a customer's question, filters by customer and answers what is active, paused or having problems.

Works with

  • Meta Ads

Frequently asked questions

Do I need x-customer-token on these routes?

No. They use only the merchant Bearer. The customer and connection come in as filters (customer and customer_integration) and are checked against your merchant.

How is this different from GET /ads/campaigns?

GET /ads/campaigns is for one customer, with x-customer-token and a required connection. The /merchants/ads route covers all customers and shows what Connect stores.

Is the data up to date?

It is the last known state, shown in synced_at. To update it, use refresh=true together with customer_integration.

Related

See everything you can do with Ads

See Connect applied to your product.

Try it for 15 days with no card, or walk our team through your use case.