Overview
Paid ad campaigns, metrics and actions.
Paid ads are where the seller spends to sell. A campaign (AdCampaign) comes from the marketplace and is synced to the API. You list campaigns, read metrics over a period, and can pause, activate or change the budget.
Where Ads fit in the journey: Grow and track.
Endpoints
| Method | Path | What it does |
|---|---|---|
GET | /v1/ad-campaigns | List campaigns |
GET | /v1/ad-campaigns/{campaignId} | Get campaign |
GET | /v1/ad-campaigns/{campaignId}/metrics | Campaign metrics |
POST | /v1/ad-campaigns/{campaignId}/actions | Act on a campaign |
POST | /v1/connections/{id}/ad-metric-syncs | Sync metrics |
All require Authorization: Bearer mk_your_api_key. See Authentication.
Campaign
| Field | Values |
|---|---|
status | active, paused, ended, draft, unknown |
adType | product, brand, display, other |
budget | { amountInCents, period }, with period daily or total, or null |
nativeType and externalStatus keep the marketplace's original value.
Metrics
The series has period, granularity (day, week or month) and timezone, as in Metrics. The values:
impressions,clicks,orders,unitsspendInCentsandrevenueInCentsctrBps = clicks × 10000 ÷ impressionsroasBps = revenueInCents × 10000 ÷ spendInCents: ROAS 5.0 is50000
The API stores only the counts. CTR and ROAS are calculated on read, in each bucket, because ratios do not add up. A zero or null denominator gives null.
Revised data
The marketplace revises numbers for up to 3 days. The latest days can change. The daily sync rewrites that window. Each marketplace keeps history for a limited time: asking for days beyond it returns 400.
Actions
Pause, activate and change budget run as a job (ad_campaign.action), with 202. An ended campaign returns 409. Not every marketplace allows actions: when it is read-only, the response is 422.
Errors
404: campaign from another account.422: the Connection does not offer the capability (ads.readorads.manage).