View as Markdown
TikTok Ads Manager icon

TikTok Ads Manager ACTION

Create or Update Ad Group

Create a new TikTok ad group or update an existing one. Omit adgroup_id to create; provide it to update. Ad groups control placement, targeting, budget, schedule, bidding, and optimization within a campaign. billing_event must correspond to the chosen optimization_goal — e.g., CLICK → CPC, CONVERT/INSTALL → OCPM, REACH/SHOW → CPM, ENGAGED_VIEW → CPV. Use campaign IDs from Create or Update Campaign or List Campaigns. For create, see documentation. For update, see documentation.
  • Action
  • Writes data
  • OAuth
  • SDK
  • MCP

IMPLEMENTATION

Call this tool

Connect a user's TikTok Ads Manager account once, then configure and run Create or Update Ad Group from your backend or agent.

import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const result = await pd.actions.run({
  id: "tiktok_ads_manager-create-or-update-ad-group",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    tiktok_ads_manager: { authProvisionId: "apn_xxxxxxx" },
    advertiserId: "Advertiser ID",
    adgroupId: "Ad Group ID",
  },
})

console.log(result)

SCHEMA

Inputs

Pipedream supplies the connected account. Your application provides the operation-specific values below. Dynamic inputs are resolved against that user's account.

Create or Update Ad Group inputs
Property Type Description
advertiserId Advertiser ID string
Your TikTok Ads Manager advertiser ID. Find it in the Ads Manager URL after aadvid= (e.g., aadvid=7123456789012345678). Also visible under Account Info in Business Center.
Required
adgroupId Ad Group ID string
ID of an existing ad group to update. Omit to create a new ad group. Use List Ad Groups to find existing IDs.
Optional
campaignId Campaign ID string
Campaign to place this ad group in. Required for new ad groups. Use List Campaigns to find campaign IDs.
Optional
adgroupName Ad Group Name string
Name for the ad group. Maximum 512 characters.
Required
placementType Placement Type string
PLACEMENT_TYPE_AUTOMATIC lets TikTok optimize placements. PLACEMENT_TYPE_NORMAL requires you to specify placements manually.
Optional
placements Placements string[]
Required when placement_type is PLACEMENT_TYPE_NORMAL. Apps where your ads will be delivered. Example: ["PLACEMENT_TIKTOK"].
Optional
budgetMode Budget Mode string
BUDGET_MODE_DAY for a daily cap; BUDGET_MODE_TOTAL for a lifetime total; BUDGET_MODE_DYNAMIC_DAILY_BUDGET for an average daily budget over a week (ad groups only); BUDGET_MODE_INFINITE for no budget cap (non-CBO campaigns only).
Required
budget Budget string
Budget amount in the account's currency. Example: 50.00 for $50 USD.
Required
scheduleType Schedule Type string
SCHEDULE_FROM_NOW starts immediately; end time is auto-set 10 years out. SCHEDULE_START_END requires both start and end times. budget_mode: BUDGET_MODE_TOTAL requires SCHEDULE_START_END.
Required
scheduleStartTime Schedule Start Time string
Ad group start time in UTC+0, format YYYY-MM-DD HH:MM:SS. Can be up to 12 hours before current time.
Required
scheduleEndTime Schedule End Time string
Ad group end time in UTC+0, format YYYY-MM-DD HH:MM:SS. Required when schedule_type is SCHEDULE_START_END or budget_mode is BUDGET_MODE_TOTAL.
Optional
optimizationGoal Optimization Goal string
What TikTok optimizes for. Common values: CLICK, CONVERT, INSTALL, REACH, SHOW, ENGAGED_VIEW, IN_APP_EVENT, VALUE.
Required
billingEvent Billing Event string
What you pay for. Must correspond to optimization_goal: CLICK/PAGE_VISIT → CPC; CONVERT/INSTALL/IN_APP_EVENT/LEAD_GENERATION → OCPM; REACH/SHOW → CPM; ENGAGED_VIEW/ENGAGED_VIEW_FIFTEEN → CPV.
Required
pacing Pacing string
PACING_MODE_SMOOTH distributes budget evenly over the schedule. PACING_MODE_FAST spends budget and produces results as fast as possible.
Required
bidType Bid Type string
Bidding strategy. BID_TYPE_NO_BID = automatic. BID_TYPE_CUSTOM = target cost cap. See TikTok bidding documentation for details.
Optional
bidPrice Bid Price string
Target bid amount in the account currency. Required when bid_type is BID_TYPE_CUSTOM.
Optional
locationIds Location IDs string[]
Target geographic locations by TikTok location ID. Example: 6252001 = United States, 6269131 = United Kingdom.
Optional
ageGroups Age Groups string[]
Target age groups. Leave blank for all ages.
Optional
gender Gender string
Target gender. GENDER_UNLIMITED targets all genders.
Optional
interestCategoryIds Interest Category IDs string[]
TikTok interest category IDs for audience targeting. Leave blank to skip interest targeting.
Optional
operationStatus Status string
Operational status. ENABLE = active, DISABLE = paused.
Optional

REFERENCE

Tool details

Behavior hints are published with the component in the Pipedream registry and surface as MCP tool annotations, so an agent can reason about a tool before it calls it.

Registry key
tiktok_ads_manager-create-or-update-ad-group
Version
0.0.2
App
TikTok Ads Manager
Authentication
OAuth
Read-only
No
Destructive
No
Open world
Yes