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>",
  "ad_group_id": "<string>",
  "keyword_id": "<string>",
  "keyword_text": "<string>",
  "keyword_match_type": "<string>",
  "org_id": "<string>",
  "before_status": "<string>",
  "before_bid": "<string>",
  "before_daily_budget": "<string>",
  "idempotency_key": "<string>",
  "dry_run": true
}
'

import requests

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

payload = {
    "campaign_id": "<string>",
    "ad_group_id": "<string>",
    "keyword_id": "<string>",
    "keyword_text": "<string>",
    "keyword_match_type": "<string>",
    "org_id": "<string>",
    "before_status": "<string>",
    "before_bid": "<string>",
    "before_daily_budget": "<string>",
    "idempotency_key": "<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>',
    ad_group_id: '<string>',
    keyword_id: '<string>',
    keyword_text: '<string>',
    keyword_match_type: '<string>',
    org_id: '<string>',
    before_status: '<string>',
    before_bid: '<string>',
    before_daily_budget: '<string>',
    idempotency_key: '<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>',
    'ad_group_id' => '<string>',
    'keyword_id' => '<string>',
    'keyword_text' => '<string>',
    'keyword_match_type' => '<string>',
    'org_id' => '<string>',
    'before_status' => '<string>',
    'before_bid' => '<string>',
    'before_daily_budget' => '<string>',
    'idempotency_key' => '<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  \"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  \"before_bid\": \"<string>\",\n  \"before_daily_budget\": \"<string>\",\n  \"idempotency_key\": \"<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  \"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  \"before_bid\": \"<string>\",\n  \"before_daily_budget\": \"<string>\",\n  \"idempotency_key\": \"<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  \"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  \"before_bid\": \"<string>\",\n  \"before_daily_budget\": \"<string>\",\n  \"idempotency_key\": \"<string>\",\n  \"dry_run\": true\n}")
  .asString();

{
  "confirmed": {
    "status": "<string>",
    "serving_status": "<string>",
    "display_status": "<string>",
    "serving_state_reasons": [
      "<string>"
    ],
    "bid": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "daily_budget": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "modification_time": "<string>"
  },
  "applied": true,
  "dry_run": true,
  "action_id": 123,
  "replayed": true,
  "baseline_unverified": true,
  "would_send": {}
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "class": "<unknown>",
    "fields": {},
    "apple": {
      "messageCode": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  },
  "confirmed": {
    "status": "<string>",
    "serving_status": "<string>",
    "display_status": "<string>",
    "serving_state_reasons": [
      "<string>"
    ],
    "bid": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "daily_budget": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "modification_time": "<string>"
  },
  "action_id": 123,
  "replayed": true
}

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

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "class": "<unknown>",
    "fields": {},
    "apple": {
      "messageCode": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  },
  "confirmed": {
    "status": "<string>",
    "serving_status": "<string>",
    "display_status": "<string>",
    "serving_state_reasons": [
      "<string>"
    ],
    "bid": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "daily_budget": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "modification_time": "<string>"
  },
  "action_id": 123,
  "replayed": true
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "class": "<unknown>",
    "fields": {},
    "apple": {
      "messageCode": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  },
  "confirmed": {
    "status": "<string>",
    "serving_status": "<string>",
    "display_status": "<string>",
    "serving_state_reasons": [
      "<string>"
    ],
    "bid": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "daily_budget": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "modification_time": "<string>"
  },
  "action_id": 123,
  "replayed": true
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "class": "<unknown>",
    "fields": {},
    "apple": {
      "messageCode": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  },
  "confirmed": {
    "status": "<string>",
    "serving_status": "<string>",
    "display_status": "<string>",
    "serving_state_reasons": [
      "<string>"
    ],
    "bid": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "daily_budget": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "modification_time": "<string>"
  },
  "action_id": 123,
  "replayed": true
}

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

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "class": "<unknown>",
    "fields": {},
    "apple": {
      "messageCode": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  },
  "confirmed": {
    "status": "<string>",
    "serving_status": "<string>",
    "display_status": "<string>",
    "serving_state_reasons": [
      "<string>"
    ],
    "bid": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "daily_budget": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "modification_time": "<string>"
  },
  "action_id": 123,
  "replayed": true
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "class": "<unknown>",
    "fields": {},
    "apple": {
      "messageCode": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  },
  "confirmed": {
    "status": "<string>",
    "serving_status": "<string>",
    "display_status": "<string>",
    "serving_state_reasons": [
      "<string>"
    ],
    "bid": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "daily_budget": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "modification_time": "<string>"
  },
  "action_id": 123,
  "replayed": true
}

{
  "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 bid, or change a campaign daily budget. Bids can be changed only at the keyword level; ad-group bids cannot be changed. 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. Campaign management must be enabled for the account, and the user needs Manage Apple Ads campaigns permission and an Apple connection that allows changes. Accounts without the Apple Ads report and accounts with the Apple Ads report only (campaign management not enabled) receive 404. Send exactly one of status, bid, or daily_budget with the matching before_* value. bid and daily_budget are objects {"amount": "<decimal string>", "currency": "<three-letter code>"} in the advertising account's own currency, never converted; a plain number or string there is refused with 422. before_bid and before_daily_budget accept the same object or a plain decimal string. idempotency_key is required (in the body, or via the Idempotency-Key header when the body has none); a request without it is refused with 422. Resending the same change with the same idempotency_key returns the original result with replayed: true. With the Idempotency-Key header, the API also caches successful (2xx) answers for 24 hours: a byte-identical resend gets the cached answer without replayed, and a different body with the same header key gets 409 idempotency_conflict. A dry run consumes its key: send the live change with a different key, otherwise you get the dry-run result back. dry_run: true simulates only and returns would_send. Query parameters are refused with 400 invalid_request; put every field, including dry_run, in the JSON body (max 64 KB). Unknown body fields are refused with 400 invalid_request and reason unsupported_parameter. 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, except a bid or budget change on an entity with no confirmed history, which is always counted as an increase (`baseline_unverified: true`). Pending changes and changes with an unknown outcome count too. A bid or budget increase cannot exceed three times the last amount Qonversion saw Apple confirm for the entity; when there is no confirmed history, the ceiling is not applied and the result carries `baseline_unverified: true`. Every refusal uses the V4 error envelope {error: {type, code, message}}. Specific codes on 4xx refusals, such as value_changed and per_minute, are preserved. Additional fields may include error.class, error.fields, error.apple and confirmed. Validation refusals use invalid_data, Apple refusals use apple_refused, and an unclassified refusal without a specific code uses upstream_refused. A request body larger than 64 KB returns HTTP 413 with the same V4Error JSON, with or without the Idempotency-Key header. Every 5xx response carries a generic V4Error body (code storage_error; network_error when the API itself timed out waiting for the result) without the specific reason or action_id. After 409, read the current value before trying again. A 502 or 504 leaves the outcome unknown; a retry with the same idempotency_key never re-sends the change — it returns the recorded outcome (or 409 in_progress / already_applied, or 502 again when the earlier attempt never reported back). Read the entity's current value before making any new change.

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>",
  "ad_group_id": "<string>",
  "keyword_id": "<string>",
  "keyword_text": "<string>",
  "keyword_match_type": "<string>",
  "org_id": "<string>",
  "before_status": "<string>",
  "before_bid": "<string>",
  "before_daily_budget": "<string>",
  "idempotency_key": "<string>",
  "dry_run": true
}
'

import requests

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

payload = {
    "campaign_id": "<string>",
    "ad_group_id": "<string>",
    "keyword_id": "<string>",
    "keyword_text": "<string>",
    "keyword_match_type": "<string>",
    "org_id": "<string>",
    "before_status": "<string>",
    "before_bid": "<string>",
    "before_daily_budget": "<string>",
    "idempotency_key": "<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>',
    ad_group_id: '<string>',
    keyword_id: '<string>',
    keyword_text: '<string>',
    keyword_match_type: '<string>',
    org_id: '<string>',
    before_status: '<string>',
    before_bid: '<string>',
    before_daily_budget: '<string>',
    idempotency_key: '<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>',
    'ad_group_id' => '<string>',
    'keyword_id' => '<string>',
    'keyword_text' => '<string>',
    'keyword_match_type' => '<string>',
    'org_id' => '<string>',
    'before_status' => '<string>',
    'before_bid' => '<string>',
    'before_daily_budget' => '<string>',
    'idempotency_key' => '<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  \"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  \"before_bid\": \"<string>\",\n  \"before_daily_budget\": \"<string>\",\n  \"idempotency_key\": \"<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  \"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  \"before_bid\": \"<string>\",\n  \"before_daily_budget\": \"<string>\",\n  \"idempotency_key\": \"<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  \"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  \"before_bid\": \"<string>\",\n  \"before_daily_budget\": \"<string>\",\n  \"idempotency_key\": \"<string>\",\n  \"dry_run\": true\n}")
  .asString();

{
  "confirmed": {
    "status": "<string>",
    "serving_status": "<string>",
    "display_status": "<string>",
    "serving_state_reasons": [
      "<string>"
    ],
    "bid": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "daily_budget": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "modification_time": "<string>"
  },
  "applied": true,
  "dry_run": true,
  "action_id": 123,
  "replayed": true,
  "baseline_unverified": true,
  "would_send": {}
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "class": "<unknown>",
    "fields": {},
    "apple": {
      "messageCode": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  },
  "confirmed": {
    "status": "<string>",
    "serving_status": "<string>",
    "display_status": "<string>",
    "serving_state_reasons": [
      "<string>"
    ],
    "bid": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "daily_budget": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "modification_time": "<string>"
  },
  "action_id": 123,
  "replayed": true
}

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

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "class": "<unknown>",
    "fields": {},
    "apple": {
      "messageCode": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  },
  "confirmed": {
    "status": "<string>",
    "serving_status": "<string>",
    "display_status": "<string>",
    "serving_state_reasons": [
      "<string>"
    ],
    "bid": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "daily_budget": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "modification_time": "<string>"
  },
  "action_id": 123,
  "replayed": true
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "class": "<unknown>",
    "fields": {},
    "apple": {
      "messageCode": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  },
  "confirmed": {
    "status": "<string>",
    "serving_status": "<string>",
    "display_status": "<string>",
    "serving_state_reasons": [
      "<string>"
    ],
    "bid": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "daily_budget": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "modification_time": "<string>"
  },
  "action_id": 123,
  "replayed": true
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "class": "<unknown>",
    "fields": {},
    "apple": {
      "messageCode": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  },
  "confirmed": {
    "status": "<string>",
    "serving_status": "<string>",
    "display_status": "<string>",
    "serving_state_reasons": [
      "<string>"
    ],
    "bid": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "daily_budget": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "modification_time": "<string>"
  },
  "action_id": 123,
  "replayed": true
}

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

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "class": "<unknown>",
    "fields": {},
    "apple": {
      "messageCode": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  },
  "confirmed": {
    "status": "<string>",
    "serving_status": "<string>",
    "display_status": "<string>",
    "serving_state_reasons": [
      "<string>"
    ],
    "bid": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "daily_budget": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "modification_time": "<string>"
  },
  "action_id": 123,
  "replayed": true
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "class": "<unknown>",
    "fields": {},
    "apple": {
      "messageCode": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  },
  "confirmed": {
    "status": "<string>",
    "serving_status": "<string>",
    "display_status": "<string>",
    "serving_state_reasons": [
      "<string>"
    ],
    "bid": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "daily_budget": {
      "amount": "2.50",
      "currency": "EUR"
    },
    "modification_time": "<string>"
  },
  "action_id": 123,
  "replayed": true
}

{
  "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.

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: if it disagrees with a status Qonversion recently saw Apple confirm, the change is refused with 409 value_changed.

bid

object

New bid. Keyword level only — ad-group bids cannot be changed. Must be an {amount, currency} object; a plain number or string is refused with 422.

Show child attributes

before_bid

Required with bid: the current bid, as a decimal string or an {amount, currency} object. A new bid more than three times the last bid Qonversion saw Apple confirm is refused with 422. When there is no confirmed history the ceiling is not applied and the response says so with baseline_unverified.

daily_budget

object

New daily budget. Campaign level only. Must be an {amount, currency} object; a plain number or string is refused with 422.

Show child attributes

before_daily_budget

Required with daily_budget: the current daily budget, as a decimal string or an {amount, currency} object. The same three-times ceiling applies as for bids.

idempotency_key

string

Required — in the body, or via the Idempotency-Key header when the body has none (a key in the body wins); a request without it is refused with 422. Resending the same change with the same idempotency_key returns the original result with replayed: true. Reusing the key for a different change returns 409 idempotency_key_reuse. With the Idempotency-Key header, the API also caches successful (2xx) answers for 24 hours: a byte-identical resend gets the cached answer without replayed, and a different body with the same header key gets 409 idempotency_conflict. A dry run consumes its key: send the live change with a different key, otherwise you get the dry-run result back.

Maximum string length: 64

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. A repeat of an earlier request with the same idempotency_key returns that request's stored result with replayed: true.

confirmed

object

required

The entity's values as Apple confirmed them after the change, or null when Apple did not return them. Verify a change from this value, not by re-reading the report.

Option 1
Option 2

Show child attributes

applied

boolean

required

The change was submitted to Apple.

dry_run

boolean

required

True when nothing was sent.

action_id

integer<int64>

required

Identifier of this change; include it when contacting support.

replayed

boolean

Present and true when this response repeats the stored result of an earlier request with the same idempotency_key; nothing was changed again.

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 (an array of one element for a keyword).

object
object[]

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