asc-apple-ads

asc Apple Ads

Run Apple Ads work through asc ads. Apple Ads credentials are separate from App Store Connect credentials; asc auth login does not configure Ads.

Pick the API first

• Direct asc ads <resource> ... commands use Apple Ads Platform API v1 and an ad account ID.
• Deprecated Campaign Management API v5 commands live under asc ads v5 ... and use an organization ID. Apple retires v5 on January 26, 2027.
• Never substitute an org ID for an ad account ID. The CLI keeps them separate.
• Run the exact leaf command with --help before building a request file. Platform v1 payloads and response envelopes differ from v5; the CLI does not translate them.
• For non-interactive pipelines, pass --file - to read a JSON request body from stdin; the CLI rejects it when stdin is a terminal.
• Resource, report, upload, and raw commands emit lossless JSON. Use jq for projections instead of asking for table or markdown output.

Authenticate and pin the account

Store both contexts when a profile must support v1 and legacy v5:

asc ads auth login \
  --name "Marketing" \
  --client-id "$ASC_ADS_CLIENT_ID" \
  --team-id

For CI, set Ads-specific variables and bypass the host keychain:

ASC_ADS_PRIVATE_KEY and ASC_ADS_PRIVATE_KEY_B64 also work. If another trusted process minted a short-lived token, set ASC_ADS_ACCESS_TOKEN; scoped v1 calls still need an ad account ID.

Check auth without printing a token:

Discovery calls Platform v1 GET /v1/me and GET /v1/acls. Compare each ACL's ad-account ID, name, organization ID, and roles; never select the first result automatically. Print the chosen account before any mutation, then pass both --ads-profile "Marketing" and --ad-account "987654" when more than one profile or account is available.

For named profiles, the profile's ad_account_id and org_id stand alone; they do not inherit context from another profile or root config. V1 context precedence is --ad-account, ASC_ADS_AD_ACCOUNT_ID, the selected profile, then profile-less root config. Legacy v5 uses the matching --org and ASC_ADS_ORG_ID chain.

Start read-only

Identity and ACL calls need no ad account context:

Then prove the selected account with a small app search:

App search requires at least one of --query, --cpids, or --return-owned-apps. Storefronts use comma-separated ISO alpha-2 codes. Add --paginate only when every search result is needed.

Use each resource's find command for inventory. Most v1 queries put filters, sorting, and pagination in a JSON object. A subordinate-resource filter looks like this:

Omitting --file from campaigns find requests the default first page. To control or exhaust the result set, use pagination.offset, pageSize, and fetchTotalCount in a query file, read the response pagination, and advance the offset until complete. This command has no --paginate flag. Platform filters use the singular value; do not copy v5 Selector fields such as conditions or plural values, which current asc rejects before auth.

The direct v1 tree also covers ad accounts and advertiser resources; app eligibility, locales, product pages, and rejection reasons; brands, business categories, locations, location groups, creatives, and assets; geographic targeting and shared budgets; reports for apps and brands; insights, suggestions, recommendations, and change history. Discover the exact leaf instead of falling back to raw HTTP:

Keyword queries need a selector file. Targeting keywords require an id, adGroupId, or campaignId filter. Negative keywords require id or adGroupId; campaign-level negative keywords combine campaignId with an adGroupId filter whose operator is IS_NULL.

Reports and optimization

V1 reports require an endpoint-specific body. Dates live under timeRange, page controls use offset and pageSize, and campaign or ad-group IDs belong in filters:

Report commands do not accept --paginate; change pagination in the body. Inspect the leaf help because report entities accept different groupBy and option values.

Recommendations and suggestions also use endpoint-specific bodies. Applying or dismissing recommendations can change spend and requires --confirm:

Guard mutations

Do not mutate until the user has approved the ad account, resource type, target IDs, and reviewed payload. Keep request JSON in files; never invent fields from a related v5 schema.

Campaign creation may start spending. CampaignCreate requires adAccountId, billingEvent, dailyBudget, name, promotedObjectId, promotedObjectType, and targeting. The CLI sends the file unchanged: --ad-account selects the request context but does not inject adAccountId into the JSON. Start from this paused shape, replace every placeholder with values read from the selected account, and recheck the current Apple v1 schema for any account-specific requirements:

A payload with explicit top-level "status":"PAUSED" can run without --confirm; an omitted or non-paused status requires it.

Campaign updates need --confirm when they can change budget, targeting, bids, delivery, dates, or status. A name-only update or a name plus PAUSED status does not. Deletes, bulk creates or updates, recommendation apply or dismiss calls, budget-order writes, and other operationally risky mutations require confirmation before auth or network access.

Ad-group creation and keyword bulk writes are examples of always-confirmed delivery or targeting changes. V1 bulk keyword files use wrapper objects such as KeywordCreateBulkRequest, not the v5 raw-array shape:

Shared budgets use the budget-orders command group. Create, update, and delete are context-free but require confirmation; view and find accept optional ad-account context.

Ad-account creation also requires --confirm because its account family cannot change and Apple provides no delete endpoint. An ad-account update containing delegations requires confirmation because it replaces the complete list.

Use the dedicated multipart command for brand assets. Poll until Apple finishes processing:

Only use an asset when eligibility.status is ELIGIBLE; for LIMITED, inspect allowedGroups. Do not attach PENDING or INELIGIBLE assets.

Raw requests

Use first-class commands for routine work. Raw v1 requests accept only v1/... paths or https://api.ads.apple.com/v1/... URLs:

Unknown mutations fail closed, and risky known mutations require --confirm. The raw command rejects multipart asset upload; use asc ads assets upload.

Keep legacy calls explicit:

Migrate v5 one command at a time

Keep existing v5 payloads under asc ads v5 until each script has a reviewed v1 body and response parser. Common moves:

Seven v5 leaves have no one-command v1 replacement: product-page countries, product-page devices, targeting-keyword bulk delete, both negative-keyword bulk deletes, and impression-share report list and view. Do not pretend that geo search, insights impression-share, or single-resource deletes preserve those contracts.

Finish live tests cleanly

• Start with ACL discovery and a one-result app search.
• Use a unique timestamped name and explicit PAUSED status for disposable campaign tests.
• Save every created ID from JSON output.
• Pause spend-bearing resources before checking anything else.
• Reread a test campaign with asc ads campaigns view --ads-profile "Marketing" --ad-account "987654" --campaign "campaign-id" --output json.
• Delete only test-created campaigns with asc ads campaigns delete --ads-profile "Marketing" --ad-account "987654" --campaign "campaign-id" --confirm; do not delete a pre-existing parent.
• Run the same campaigns view again. Treat Apple's not-found response as cleanup proof; report any campaign that still exists or could not be removed.