Creating a DPA Campaign - Step-by-Step

The following example assumes you have installed, configured, and authorized your app and user using twurl. twurl is a command-line tool in the spirit of cURL that gracefully handles X OAuth authentication. twurl is a great tool for quickly testing and debugging Ads API (and REST API) functionality. To see the full headers of the request and response, use -t to trace the call, roughly equivalent to cURL’s -v option.

For this example, we will create a Dynamic Product Ads (DPA) campaign.

Retrieve the account id.

twurl -H ads-api.x.com /12/accounts/

{
  "request": {
    "params": {}
  },
  "data": [
    {
      "name": "Test account for @AdsAPI",
      "timezone": "America/Los_Angeles",
      "timezone_switch_at": null,
      "id": "xxxxxx",
      "created_at": "2014-03-09T00:41:49Z",
      "salt": "f9f9d5a5f23075c618da5eb1d1a9df57",
      "updated_at": "2015-01-29T00:41:49Z",
      "approval_status": "ACCEPTED",
      "deleted": false
    }
  ],
  "data_type": "account",
  "total_count": 1,
  "next_cursor": null
}

Retrieve the funding instrument id.
Hit the GET accounts/:account_id/funding_instruments API using the account id retrieved in the previous command.

twurl -H ads-api.x.com /12/accounts/xxxxxx/funding_instruments

{
  "data": [
    {
      "cancelled": true,
      "created_at": "2014-03-09T00:41:49Z",
      "credit_limit_local_micro": null,
      "currency": "USD",
      "deleted": false,
      "description": null,
      "end_time": null,
      "funded_amount_local_micro": null,
      "id": "yyyy",
      "type": null,
      "updated_at": "2014-05-29T00:41:49Z"
    }
  ],
  "data_type": "funding_instrument",
  "next_cursor": null,
  "request": {
    "params": {
      "account_id": "xxxxxx"
    }
  },
  "total_count": 1
}

Step 1: Create campaign

Create a campaign and associate it with the funding instrument.
Specify a start time and a budget for the campaign.

• Required fields: funding instrument, campaign name, budget (total/daily), start time, and ads account ID

twurl -H ads-api.x.com -d "funding_instrument_id={FUNDING_INSTRUMENT_ID}&name={CAMPAIGN_NAME}&total_budget_amount_local_micro={TOTAL_BUDGET}&daily_budget_amount_local_micro={DAILY_BUDGET}&start_time={START_TIME}" /12/accounts/{ADS_ACCOUNT_ID}/campaigns | jq

Step 2: Create line item with Sales objective

Create a line item associated with the campaign.

• Required fields: campaign id (from Step 1), product type, placements, objective, goal, entity status, primary web event tag, catalog id, product set id, creative_source, ads_account_id
• catalog_id and product_set_id can be found in your shopping manager
• creative_source should always be DYNAMIC_PRODUCT_CREATIVE
• objective should always be WEBSITE_CLICKS
• goal should always be WEBSITE_CONVERSIONS

twurl -H ads-api.x.com -d "campaign_id={CAMPAIGN_ID}&product_type={product_type}&placements={PLACEMENTS}&objective=WEBSITE_CLICKS&goal=WEBSITE_CONVERSIONS&entity_status={entity_status}&primary_web_event_tag={WEB_EVENT_TAG}&catalog_id={catalog_id}&product_set_id={product_set_id}&creative_source=DYNAMIC_PRODUCT_CREATIVE" /12/accounts/{ADS_ACCOUNT_ID}/line_items | jq

• After this step, the campaign will be available to see in X’s Ads Manager.

Step 3: Create DPA card

Create a DPA card.

• Required parameters: ads account ID and URL:
• The URL must start with https://twitter.com - any additional UTM can be appended on afterwards like in the example below:
  • https://twitter.com?utm_source=%7B%7Bsite_source%7D%7D
• Optionally, you can choose the format of your card by specifying creative_type with one of the following values: “CAROUSEL”, “SINGLE”, “COLLECTION”. If not specified, your card will be created as a carousel card.

twurl -X POST -H ads-api.twitter.com -A "Content-Type: application/json" "/12/accounts/{ADS_ACCOUNT_ID}/dynamic_product_cards" -d '{"url": "{URL}", "creative_type": "{CREATIVE_TYPE}"}' | jq

Step 4: Create Post

Create a post.

• Required parameters: ads account ID, user ID, card URI (from Step 3), text, name, & dynamic product ad
• dynamic_product_ad should always be set to true

twurl -X POST -H "https://ads-api.twitter.com" "/12/accounts/{ADS_ACCOUNT_ID}/tweet?as_user_id={USER_ID}1&card_uri=card%3A%2F%2F{CARD_URI}&text={POST_TEXT}&name={POST_NAME}%201&dynamic_product_ad=true" | jq

Step 5: Associate post with line item

Associate the post with the line item.

• Required parameters: ads account id, line item id (from Step 2) and tweet id (id_str from Step 4)

twurl -X POST -H "https://ads-api.twitter.com" "/12/accounts/{ADS_ACCOUNT_ID}/promoted_tweets?line_item_id={line_item_id}&tweet_ids={tweet_id}" | jq

If advertisers want to see the card in the UI - it will also be available.