# Create or Update Ad Group — TikTok Ads Manager

> 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…

- Key: `tiktok_ads_manager-create-or-update-ad-group`
- Type: Action (Write)
- Version: 0.0.2
- App: TikTok Ads Manager (`tiktok_ads_manager`) — https://pipedream.com/apps/tiktok-ads-manager.md
- This page (HTML): https://pipedream.com/apps/tiktok-ads-manager/actions/create-or-update-ad-group
- Hints: open-world
- Source: https://github.com/PipedreamHQ/pipedream/blob/master/components/tiktok_ads_manager/actions/create-or-update-ad-group/create-or-update-ad-group.mjs

## Description

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](https://business-api.tiktok.com/portal/docs/create-an-ad-group-reference/v1.3). For update, see [documentation](https://business-api.tiktok.com/portal/docs/update-an-ad-group/v1.3).

## Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `advertiserId` | `string` | Yes | 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. |
| `adgroupId` | `string` | No | ID of an existing ad group to update. Omit to create a new ad group. Use List Ad Groups to find existing IDs. |
| `campaignId` | `string` | No | Campaign to place this ad group in. Required for new ad groups. Use List Campaigns to find campaign IDs. |
| `adgroupName` | `string` | Yes | Name for the ad group. Maximum 512 characters. |
| `placementType` | `string` | No | PLACEMENT_TYPE_AUTOMATIC lets TikTok optimize placements. PLACEMENT_TYPE_NORMAL requires you to specify placements manually. |
| `placements` | `string[]` | No | Required when placement_type is PLACEMENT_TYPE_NORMAL. Apps where your ads will be delivered. Example: ["PLACEMENT_TIKTOK"]. |
| `budgetMode` | `string` | Yes | 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). |
| `budget` | `string` | Yes | Budget amount in the account's currency. Example: 50.00 for $50 USD. |
| `scheduleType` | `string` | Yes | 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. |
| `scheduleStartTime` | `string` | Yes | Ad group start time in UTC+0, format YYYY-MM-DD HH:MM:SS. Can be up to 12 hours before current time. |
| `scheduleEndTime` | `string` | No | 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. |
| `optimizationGoal` | `string` | Yes | What TikTok optimizes for. Common values: CLICK, CONVERT, INSTALL, REACH, SHOW, ENGAGED_VIEW, IN_APP_EVENT, VALUE. |
| `billingEvent` | `string` | Yes | 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. |
| `pacing` | `string` | Yes | PACING_MODE_SMOOTH distributes budget evenly over the schedule. PACING_MODE_FAST spends budget and produces results as fast as possible. |
| `bidType` | `string` | No | Bidding strategy. BID_TYPE_NO_BID = automatic. BID_TYPE_CUSTOM = target cost cap. See TikTok bidding documentation for details. |
| `bidPrice` | `string` | No | Target bid amount in the account currency. Required when bid_type is BID_TYPE_CUSTOM. |
| `locationIds` | `string[]` | No | Target geographic locations by TikTok location ID. Example: 6252001 = United States, 6269131 = United Kingdom. |
| `ageGroups` | `string[]` | No | Target age groups. Leave blank for all ages. |
| `gender` | `string` | No | Target gender. GENDER_UNLIMITED targets all genders. |
| `interestCategoryIds` | `string[]` | No | TikTok interest category IDs for audience targeting. Leave blank to skip interest targeting. |
| `operationStatus` | `string` | No | Operational status. ENABLE = active, DISABLE = paused. |

## Run it

**MCP**

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
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 accessToken = await pd.rawAccessToken

const transport = new StreamableHTTPClientTransport(
  new URL("https://remote.mcp.pipedream.net/v3"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "x-pd-project-id": process.env.PIPEDREAM_PROJECT_ID!,
        "x-pd-environment": "production",
        "x-pd-external-user-id": "{external_user_id}", // any stable ID for this user in your system
        "x-pd-app-slug": "tiktok_ads_manager",
      },
    },
  },
)

const mcp = new Client({ name: "my-agent", version: "1.0.0" })
await mcp.connect(transport)

const { tools } = await mcp.listTools()

// listTools() hands your model this tool's input schema, so it can
// fill the arguments itself:
const result = await mcp.callTool({
  name: "tiktok_ads_manager-create-or-update-ad-group",
  arguments: {
    advertiserId: "Advertiser ID",
    adgroupId: "Ad Group ID",
  },
})
```

**TypeScript**

```ts
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)
```

**cURL**

```bash
curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \
  -H "Content-Type: application/json" \
  -H "X-PD-Environment: production" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "external_user_id": "{external_user_id}",
    "id": "tiktok_ads_manager-create-or-update-ad-group",
    "configured_props": {
      "tiktok_ads_manager": { "authProvisionId": "apn_xxxxxxx" },
      "advertiserId": "Advertiser ID",
      "adgroupId": "Ad Group ID"
    }
  }'
```

---

- App: https://pipedream.com/apps/tiktok-ads-manager.md · All apps: https://pipedream.com/apps