Manage ads
Pause or resume X campaigns, line items and ads, change their budget and bid, and delete them.
After creation an X ad changes only in status, budget and bid. Targeting and creative stay as created.
Pause or resume
PUT /v1/ads/{adId}/status pauses or resumes an ad. X has no per-ad switch, so it writes the switch of the ad's line item, which every promoted post in that line item shares.
const { data: paused } = await zernio.adcampaigns.updateAdStatus({
path: { adId: '66f0a1b2c3d4e5f6a7b8c9d0' },
body: { status: 'paused' }
});Response (200):
{ "updated": 1, "skipped": 0, "status": "paused", "configuredStatus": null }configuredStatus is always null on X, because X exposes no per-ad switch.
The campaign and line item keep their own switches:
PUT /v1/ads/campaigns/{campaignId}/statuswithplatform: "twitter"writes the campaign's switch.PUT /v1/ads/ad-sets/{adSetId}/statuswrites the line item'sentity_status.
Pausing a campaign stops everything under it. Resuming it lets a line item deliver again only if its own switch is on.
Change the budget
Send budget: { amount, type } on PUT /v1/ads/{adId}. Zernio reads where X holds the budget and writes it there, on the line item or on the campaign.
PUT /v1/ads/ad-sets/{adSetId} with platform: "twitter" changes a line item budget directly. amount is in whole currency units.
PUT /v1/ads/campaigns/{campaignId} changes a campaign budget, and name on it renames the campaign. When X holds the budget on the line item, a campaign budget returns 409.
Change the bid
bidStrategy and bidAmount on PUT /v1/ads/ad-sets/{adSetId} write the line item's bid:
bidStrategy | X bid strategy |
|---|---|
LOWEST_COST_WITHOUT_CAP | AUTO |
LOWEST_COST_WITH_BID_CAP | MAX, with bidAmount |
COST_CAP | TARGET, with bidAmount |
X decides which strategy the line item's objective allows: TARGET only on reach, followers and website clicks, and MAX not on reach or followers.
name on the same call renames the line item.
Delete
DELETE /v1/ads/{adId} removes the promoted post on X and marks the ad cancelled in Zernio, keeping its history.
Its line item goes too, but only when Zernio created it and X lists no other promoted post in it. The campaign follows on the same rule. If X refuses the promoted post delete, nothing else is touched.
DELETE /v1/ads/campaigns/{campaignId} deletes a whole campaign on purpose.
If it fails
| Error | Cause | Fix |
|---|---|---|
501 with code feature_not_available | targeting or creative sent to PUT /v1/ads/{adId} | Create a new ad with the change. |
400 with code missing_required_field, param: "roasAverageFloor" | LOWEST_COST_WITH_MIN_ROAS without roasAverageFloor | Use LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP or COST_CAP. |
422 with param: "bidStrategy" | A strategy outside the three X takes | Use LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP or COST_CAP. |
409 with code invalid_field_value | A campaign budget when the budget lives on the line item | Change the budget through the ad or line item. |
501 on a campaign duplicate | X campaigns cannot be duplicated | Create the campaign again to copy it. |
403 with code ads_allowance_exceeded | No payment method on file and 500 live ads reached | Add a card to resume. |
404 | The ad or campaign id is unknown | Read the ids from GET /v1/ads/tree. |
Related
- Update ad and Pause or resume a single ad.
- Update an ad set: line item status, budget, bid and name.
- Cancel an ad: what a delete removes on X.
- Get campaign tree: campaign, line item and ad ids.
- Limits & Errors: what X does not allow after creation.