In late Q4, we’re releasing an update to the Ads API that will allow advertisers to pause Promoted Tweets.
Pausing Promoted Tweets
An advertiser may need to pause a Promoted Tweet for a number of reasons. Whether they are cycling in different creatives, making edits to creative details, or redirecting spend to other creatives, there are a variety of instances where an advertiser may want to pause a specific ad without stopping a full ad group or campaign.
Currently, if an advertiser wants to pause a Promoted Tweet, the Ads API requires that the Tweet be deleted from the associated campaign or ad group. Conversely, if an advertiser wants to unpause a Promoted Tweet, the Ads API requires that the Tweet be re-added to the desired campaign or ad group.
With this launch, we are building a distinct “pause” functionality by introducing:
- A new
promoted_tweets PUT endpoint
-
PAUSED as a new enum for the entity_status parameter
This change will provide developers with a streamlined and consistent workflow for pausing entities.
Key Notes
-
All other entities (e.g. Campaigns, Ad Groups) already support pausing via the Ads API. With this change, we are unifying the pausing workflow across all entity types. This means that Promoted Tweets will no longer require unique workflows.
-
For the promoted_tweets endpoint, supported enums for the entity_status parameter will be ACTIVE and PAUSED.
-
This feature will unlock future development and new functionality for paused Promoted Tweets.
We highly encourage you to build support for this new feature now in order to align launch timing with the late Q4 release in Twitter’s Ads Manager.
Implementation Best Practices
In coordination with this update, we recommend making the following changes to your UI in order to maintain alignment with Twitter’s Ads Manager.
-
Phase 1 (Late Q4)
-
When a user pauses an ad in your UI, use the PUT /promoted_tweets endpoint to update entity_status to PAUSED.
-
When the promoted_tweet entity_status is PAUSED, always show the ad as “Paused” in your UI.
-
Phase 2 (Q1)
- When a Promoted Tweet has
deleted=true, show it as “Deleted” in your the UI.
These changes will be made to Twitter’s Ads Manager in a phased manner following the schedule above.
Example Request:
twurl -H ads-api.twitter.com -X PUT "/12/accounts/18ce54d4x5t/promoted_tweets/9joop8?entity_status=PAUSED"
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"promoted_tweet_id": "9joop8",
"entity_status": "PAUSED"
}
},
"data": {
"line_item_id": "7pmb8",
"id": "9joop8",
"entity_status": "PAUSED",
"created_at": "2022-09-27T23:35:53Z",
"updated_at": "2022-10-12T10:21:28Z",
"approval_status": "ACCEPTED",
"tweet_id": "1506111713715777536",
"deleted": false
}
}
To learn more about Promoted Tweets, check out this page.
Please let us know if you have any questions.
Twitter Ads API team
