Change an Apple Ads campaign, ad group or keyword

curl --request POST \
  --url https://api.qonversion.io/v4/analytics/apple-ads/entity/update \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Qonversion-Actor-Assertion: <api-key>' \
  --data '
{
  "campaign_id": "<string>",
  "idempotency_key": "<string>",
  "ad_group_id": "<string>",
  "keyword_id": "<string>",
  "keyword_text": "<string>",
  "keyword_match_type": "<string>",
  "org_id": "<string>",
  "before_status": "<string>",
  "bid": "<string>",
  "before_bid": "<string>",
  "daily_budget": "<string>",
  "before_daily_budget": "<string>",
  "dry_run": true
}
'

import requests

url = "https://api.qonversion.io/v4/analytics/apple-ads/entity/update"

payload = {
    "campaign_id": "<string>",
    "idempotency_key": "<string>",
    "ad_group_id": "<string>",
    "keyword_id": "<string>",
    "keyword_text": "<string>",
    "keyword_match_type": "<string>",
    "org_id": "<string>",
    "before_status": "<string>",
    "bid": "<string>",
    "before_bid": "<string>",
    "daily_budget": "<string>",
    "before_daily_budget": "<string>",
    "dry_run": True
}
headers = {
    "Authorization": "Bearer <token>",
    "X-Qonversion-Actor-Assertion": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'X-Qonversion-Actor-Assertion': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    campaign_id: '<string>',
    idempotency_key: '<string>',
    ad_group_id: '<string>',
    keyword_id: '<string>',
    keyword_text: '<string>',
    keyword_match_type: '<string>',
    org_id: '<string>',
    before_status: '<string>',
    bid: '<string>',
    before_bid: '<string>',
    daily_budget: '<string>',
    before_daily_budget: '<string>',
    dry_run: true
  })
};

fetch('https://api.qonversion.io/v4/analytics/apple-ads/entity/update', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.qonversion.io/v4/analytics/apple-ads/entity/update",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'campaign_id' => '<string>',
    'idempotency_key' => '<string>',
    'ad_group_id' => '<string>',
    'keyword_id' => '<string>',
    'keyword_text' => '<string>',
    'keyword_match_type' => '<string>',
    'org_id' => '<string>',
    'before_status' => '<string>',
    'bid' => '<string>',
    'before_bid' => '<string>',
    'daily_budget' => '<string>',
    'before_daily_budget' => '<string>',
    'dry_run' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Qonversion-Actor-Assertion: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api.qonversion.io/v4/analytics/apple-ads/entity/update")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Qonversion-Actor-Assertion"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"campaign_id\": \"<string>\",\n  \"idempotency_key\": \"<string>\",\n  \"ad_group_id\": \"<string>\",\n  \"keyword_id\": \"<string>\",\n  \"keyword_text\": \"<string>\",\n  \"keyword_match_type\": \"<string>\",\n  \"org_id\": \"<string>\",\n  \"before_status\": \"<string>\",\n  \"bid\": \"<string>\",\n  \"before_bid\": \"<string>\",\n  \"daily_budget\": \"<string>\",\n  \"before_daily_budget\": \"<string>\",\n  \"dry_run\": true\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.qonversion.io/v4/analytics/apple-ads/entity/update"

	payload := strings.NewReader("{\n  \"campaign_id\": \"<string>\",\n  \"idempotency_key\": \"<string>\",\n  \"ad_group_id\": \"<string>\",\n  \"keyword_id\": \"<string>\",\n  \"keyword_text\": \"<string>\",\n  \"keyword_match_type\": \"<string>\",\n  \"org_id\": \"<string>\",\n  \"before_status\": \"<string>\",\n  \"bid\": \"<string>\",\n  \"before_bid\": \"<string>\",\n  \"daily_budget\": \"<string>\",\n  \"before_daily_budget\": \"<string>\",\n  \"dry_run\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Qonversion-Actor-Assertion", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.qonversion.io/v4/analytics/apple-ads/entity/update")
  .header("Authorization", "Bearer <token>")
  .header("X-Qonversion-Actor-Assertion", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"campaign_id\": \"<string>\",\n  \"idempotency_key\": \"<string>\",\n  \"ad_group_id\": \"<string>\",\n  \"keyword_id\": \"<string>\",\n  \"keyword_text\": \"<string>\",\n  \"keyword_match_type\": \"<string>\",\n  \"org_id\": \"<string>\",\n  \"before_status\": \"<string>\",\n  \"bid\": \"<string>\",\n  \"before_bid\": \"<string>\",\n  \"daily_budget\": \"<string>\",\n  \"before_daily_budget\": \"<string>\",\n  \"dry_run\": true\n}")
  .asString();

{
  "confirmed": true,
  "applied": true,
  "dry_run": true,
  "action_id": "<string>",
  "baseline_unverified": true,
  "would_send": {}
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

Apple Ads

Change an Apple Ads campaign, ad group or keyword

Pause or enable a campaign, ad group, or keyword, change a keyword or ad-group bid, or change a campaign daily budget.

Requires Qonversion MCP authorization with the acting dashboard user and apple_ads:write scope. A project Secret Key alone is insufficient; direct callers without MCP authorization receive 403. The user needs Manage Apple Ads campaigns permission and an Apple connection that allows changes. Accounts without Apple Ads access receive 404.

Send one of status, bid, or daily_budget with the matching before_* value. Bid and budget amounts are decimal strings in the advertising account’s currency. Reuse idempotency_key for the same attempt; Idempotency-Key is an alternative when the body omits it. dry_run: true simulates only and returns would_send. Caller query parameters are refused with 400 invalid_request and reason unsupported_parameter; put dry_run in the JSON body.

Limits are per project: 10 changes per rolling minute, 60 per rolling hour, 20 enables, 20 bid increases, and 10 budget increases per rolling 24 hours. Each change stops counting 24 hours after it was made. Pauses and decreases do not count toward daily increase limits. A bid or budget increase cannot exceed three times the confirmed current amount.

After 409, read the current value before trying again. A 502 or 504 leaves the outcome unknown; check the report before retrying.

POST

analytics

apple-ads

entity

update

Change an Apple Ads campaign, ad group or keyword

curl --request POST \
  --url https://api.qonversion.io/v4/analytics/apple-ads/entity/update \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Qonversion-Actor-Assertion: <api-key>' \
  --data '
{
  "campaign_id": "<string>",
  "idempotency_key": "<string>",
  "ad_group_id": "<string>",
  "keyword_id": "<string>",
  "keyword_text": "<string>",
  "keyword_match_type": "<string>",
  "org_id": "<string>",
  "before_status": "<string>",
  "bid": "<string>",
  "before_bid": "<string>",
  "daily_budget": "<string>",
  "before_daily_budget": "<string>",
  "dry_run": true
}
'

import requests

url = "https://api.qonversion.io/v4/analytics/apple-ads/entity/update"

payload = {
    "campaign_id": "<string>",
    "idempotency_key": "<string>",
    "ad_group_id": "<string>",
    "keyword_id": "<string>",
    "keyword_text": "<string>",
    "keyword_match_type": "<string>",
    "org_id": "<string>",
    "before_status": "<string>",
    "bid": "<string>",
    "before_bid": "<string>",
    "daily_budget": "<string>",
    "before_daily_budget": "<string>",
    "dry_run": True
}
headers = {
    "Authorization": "Bearer <token>",
    "X-Qonversion-Actor-Assertion": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'X-Qonversion-Actor-Assertion': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    campaign_id: '<string>',
    idempotency_key: '<string>',
    ad_group_id: '<string>',
    keyword_id: '<string>',
    keyword_text: '<string>',
    keyword_match_type: '<string>',
    org_id: '<string>',
    before_status: '<string>',
    bid: '<string>',
    before_bid: '<string>',
    daily_budget: '<string>',
    before_daily_budget: '<string>',
    dry_run: true
  })
};

fetch('https://api.qonversion.io/v4/analytics/apple-ads/entity/update', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.qonversion.io/v4/analytics/apple-ads/entity/update",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'campaign_id' => '<string>',
    'idempotency_key' => '<string>',
    'ad_group_id' => '<string>',
    'keyword_id' => '<string>',
    'keyword_text' => '<string>',
    'keyword_match_type' => '<string>',
    'org_id' => '<string>',
    'before_status' => '<string>',
    'bid' => '<string>',
    'before_bid' => '<string>',
    'daily_budget' => '<string>',
    'before_daily_budget' => '<string>',
    'dry_run' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Qonversion-Actor-Assertion: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api.qonversion.io/v4/analytics/apple-ads/entity/update")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Qonversion-Actor-Assertion"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"campaign_id\": \"<string>\",\n  \"idempotency_key\": \"<string>\",\n  \"ad_group_id\": \"<string>\",\n  \"keyword_id\": \"<string>\",\n  \"keyword_text\": \"<string>\",\n  \"keyword_match_type\": \"<string>\",\n  \"org_id\": \"<string>\",\n  \"before_status\": \"<string>\",\n  \"bid\": \"<string>\",\n  \"before_bid\": \"<string>\",\n  \"daily_budget\": \"<string>\",\n  \"before_daily_budget\": \"<string>\",\n  \"dry_run\": true\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.qonversion.io/v4/analytics/apple-ads/entity/update"

	payload := strings.NewReader("{\n  \"campaign_id\": \"<string>\",\n  \"idempotency_key\": \"<string>\",\n  \"ad_group_id\": \"<string>\",\n  \"keyword_id\": \"<string>\",\n  \"keyword_text\": \"<string>\",\n  \"keyword_match_type\": \"<string>\",\n  \"org_id\": \"<string>\",\n  \"before_status\": \"<string>\",\n  \"bid\": \"<string>\",\n  \"before_bid\": \"<string>\",\n  \"daily_budget\": \"<string>\",\n  \"before_daily_budget\": \"<string>\",\n  \"dry_run\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Qonversion-Actor-Assertion", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.qonversion.io/v4/analytics/apple-ads/entity/update")
  .header("Authorization", "Bearer <token>")
  .header("X-Qonversion-Actor-Assertion", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"campaign_id\": \"<string>\",\n  \"idempotency_key\": \"<string>\",\n  \"ad_group_id\": \"<string>\",\n  \"keyword_id\": \"<string>\",\n  \"keyword_text\": \"<string>\",\n  \"keyword_match_type\": \"<string>\",\n  \"org_id\": \"<string>\",\n  \"before_status\": \"<string>\",\n  \"bid\": \"<string>\",\n  \"before_bid\": \"<string>\",\n  \"daily_budget\": \"<string>\",\n  \"before_daily_budget\": \"<string>\",\n  \"dry_run\": true\n}")
  .asString();

{
  "confirmed": true,
  "applied": true,
  "dry_run": true,
  "action_id": "<string>",
  "baseline_unverified": true,
  "would_send": {}
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication using the project Secret Key (prefixed with sk_), used exactly as shown in the dashboard. Endpoints that support sandbox data take an explicit environment field or parameter. All v4 public endpoints require the Secret Key — see Authentication. Never expose the Secret Key in client-side code.

X-Qonversion-Actor-Assertion

string

header

required

Authorization supplied by Qonversion MCP, naming the acting dashboard user and granted scopes. Required together with secretAuth for campaign management. Direct HTTP clients cannot supply this authorization.

Headers

Idempotency-Key

string

Alternative to the body field. Copied into idempotency_key when the body omits it.

Maximum string length: 64

Body

application/json

Exactly ONE of status, bid, daily_budget, and the matching before_* value, which is mandatory.

level

enum<string>

required

Which entity is being changed. Ids below the level are ignored.

Available options:

campaign,

ad_group,

keyword

campaign_id

string

required

Apple campaign id. A STRING: Apple ids are int64.

idempotency_key

string

required

Required. Reuse for the same attempt. A different body with the same key returns 409.

Maximum string length: 64

ad_group_id

string

Required for ad_group and keyword levels.

keyword_id

string

Required for the keyword level.

keyword_text

string

Required for the keyword level — Apple wants the keyword identity echoed back.

keyword_match_type

string

Required for the keyword level (e.g. EXACT, BROAD).

org_id

string

Optional. The organization is DERIVED server-side from the campaign; a value that disagrees with the resolved one is rejected rather than silently overriding it.

status

enum<string>

New status. ACTIVE is accepted as the keyword-level spelling of ENABLED.

Available options:

ENABLED,

PAUSED,

ACTIVE

before_status

string

Required with status. The status you believe is current — a mismatch is a 409.

bid

string

New bid, a decimal STRING in the advertising account's currency (never converted). Ad group and keyword levels.

before_bid

string

Required with bid. Also bounds the change: a bid more than three times the current confirmed one is refused. When there is no confirmed history the ceiling cannot be applied and the response says so with baseline_unverified.

daily_budget

string

New campaign daily budget, a decimal STRING in the advertising account's currency.

before_daily_budget

string

Required with daily_budget.

dry_run

boolean

Simulate only. Nothing is sent to Apple and the response carries would_send.

Response

The change was accepted by Apple, or simulated when dry_run was set.

confirmed

boolean

required

Apple confirmed the new value. false together with applied means the change was accepted but not yet reflected back.

applied

boolean

required

The change was submitted to Apple.

dry_run

boolean

required

True when nothing was sent.

action_id

string

required

Identifier of this change; include it when contacting support.

baseline_unverified

boolean

Present and true when there was no confirmed bid history for this entity, so the ×3 ceiling could NOT be applied and the change was counted as a raise. Treat it as a prompt for explicit human confirmation: it is the one signal that the server could not check the size of what it was about to do.

would_send

object

Dry runs only — the exact payload Apple would have received.

Start here

Resource guides

REST API v4

Analytics API

Legacy: API v3

Change an Apple Ads campaign, ad group or keyword

Authorizations

Headers

Body

Response