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
| Field | Type | Required | Description |
|---|---|---|---|
| customer | string | No | The uuid of one of your customers. Without it, the response includes all customers. |
| customer_integration | string | No | The uuid of a connection of one of your customers, to narrow to one account. With customer, the connection must belong to that customer. |
| status | string | No | Filters by the last known status: active or paused. |
| effective_status | string | No | Filters by the last effective status seen, such as pending_review, disapproved or with_issues. |
| refresh | boolean | No | Re-reads the response's objects from the platform and updates Connect. Requires customer_integration. |
| include_deleted | boolean | No | Includes deleted objects, with deleted_at. |
| per_page | integer | No | Items per page, from 1 to 100. The default is 15. |
| customer_uuid | string | No | In 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.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
