> ## Documentation Index > Fetch the complete documentation index at: https://documentation.qonversion.io/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /api-reference/rest-api-v4.yaml post /analytics/apple-ads/entity/update openapi: 3.0.3 info: title: Qonversion REST API v4 version: '4.0' description: >- Qonversion REST API v4 follows REST standards. It has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. servers: - url: https://api.qonversion.io/v4 description: Production security: - secretAuth: [] tags: - name: Users description: Retrieve Qonversion users - name: User Properties description: Manage user-level attributes - name: Identities description: Link Qonversion users to your own auth IDs - name: Entitlements description: Entitlement definitions and user grants - name: Purchases description: A user's purchase history - name: Products description: Products configured in the Qonversion dashboard - name: Remote Configurations description: Server-driven configuration payloads and targeting delivered to the SDK - name: Customers description: Aggregated customer records, properties, permissions, and metrics - name: Segments description: Dynamic and system segments of users - name: Experiments description: Paywall and offering A/B experiments - name: Screens description: No-code paywall screens — CRUD, publish, analytics - name: Analytics description: Charts, cards, cohorts, LTV, and insights - name: Apple Ads description: Apple Ads reports, daily series, and connection status - name: Exports description: Asynchronous data exports - name: Events description: Subscription and purchase events recorded for the project - name: Scheduled Reports description: Recurring reports delivered to external destinations - name: Integrations description: Third-party integrations configuration - name: Automations description: Event-driven automations - name: Project Settings description: Project-level configuration, secret, and store credentials paths: /analytics/apple-ads/entity/update: post: tags: - Apple Ads summary: Change an Apple Ads campaign, ad group or keyword description: >- 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. operationId: v4UpdateAppleAdsEntity parameters: - name: Idempotency-Key in: header required: false description: >- Alternative to the body field. Copied into `idempotency_key` when the body omits it. schema: type: string maxLength: 64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/V4AppleAdsEntityUpdateRequest' responses: '200': description: >- The change was accepted by Apple, or simulated when `dry_run` was set. content: application/json: schema: $ref: '#/components/schemas/V4AppleAdsEntityUpdateResult' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/V4Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/V4Error' '403': description: >- MCP write authorization, user campaign-management access, or writable Apple access is missing. content: application/json: schema: $ref: '#/components/schemas/V4Error' '404': description: Entity not found, or the account has no Apple Ads access. content: application/json: schema: $ref: '#/components/schemas/V4Error' '409': description: >- The value changed under you (the `before_*` expectation no longer matches), or this idempotency key was already used with a different request. Re-read the report; do not retry the same body. content: application/json: schema: $ref: '#/components/schemas/V4Error' '422': description: The request cannot be executed — the message names what to change content: application/json: schema: $ref: '#/components/schemas/V4Error' '429': description: >- A rate limit (per minute/hour) or a daily cap on spend-increasing actions. `Retry-After` carries the wait; a daily cap does not clear within the minute. headers: Retry-After: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/V4Error' '502': description: >- The outcome is UNKNOWN — the change may or may not have reached Apple. Never retried automatically, and you should not retry it blindly either: read the report first. content: application/json: schema: $ref: '#/components/schemas/V4Error' '503': description: Campaign management is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/V4Error' '504': description: The call timed out with the outcome unknown — same rule as 502. content: application/json: schema: $ref: '#/components/schemas/V4Error' security: - secretAuth: [] actorAssertionAuth: [] components: schemas: V4AppleAdsEntityUpdateRequest: type: object required: - level - campaign_id - idempotency_key description: >- Exactly ONE of `status`, `bid`, `daily_budget`, and the matching `before_*` value, which is mandatory. properties: level: type: string enum: - campaign - ad_group - keyword description: Which entity is being changed. Ids below the level are ignored. campaign_id: type: string description: 'Apple campaign id. A STRING: Apple ids are int64.' ad_group_id: type: string description: Required for ad_group and keyword levels. keyword_id: type: string description: Required for the keyword level. keyword_text: type: string description: >- Required for the keyword level — Apple wants the keyword identity echoed back. keyword_match_type: type: string description: Required for the keyword level (e.g. EXACT, BROAD). org_id: type: string description: >- 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: type: string enum: - ENABLED - PAUSED - ACTIVE description: >- New status. ACTIVE is accepted as the keyword-level spelling of ENABLED. before_status: type: string description: >- Required with `status`. The status you believe is current — a mismatch is a 409. bid: type: string description: >- New bid, a decimal STRING in the advertising account's currency (never converted). Ad group and keyword levels. before_bid: type: string description: >- 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: type: string description: >- New campaign daily budget, a decimal STRING in the advertising account's currency. before_daily_budget: type: string description: Required with `daily_budget`. idempotency_key: type: string maxLength: 64 description: >- Required. Reuse for the same attempt. A different body with the same key returns 409. dry_run: type: boolean description: >- Simulate only. Nothing is sent to Apple and the response carries `would_send`. V4AppleAdsEntityUpdateResult: type: object required: - confirmed - applied - dry_run - action_id properties: confirmed: type: boolean description: >- Apple confirmed the new value. `false` together with `applied` means the change was accepted but not yet reflected back. applied: type: boolean description: The change was submitted to Apple. dry_run: type: boolean description: True when nothing was sent. action_id: type: string description: Identifier of this change; include it when contacting support. baseline_unverified: type: boolean description: >- 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: type: object description: Dry runs only — the exact payload Apple would have received. additionalProperties: true V4Error: type: object required: - error properties: error: type: object required: - type - code - message properties: type: type: string enum: - request - resource - logical - internal code: type: string description: | Machine-readable snake_case error code. Examples include `invalid_data`, `invalid_request`, `invalid_product_id`, `not_found`, `already_exists`, `offering_already_exists`, `product_not_in_project`, `cannot_set_main_directly`, `cannot_demote_main`, `cannot_patch_experiment_variant`, `cannot_delete_experiment_variant`, and `cannot_setmain_experiment_variant`. Resource-specific codes are documented on the corresponding reference page. message: type: string description: Human-readable description. May change; do not parse. details: type: array nullable: true description: Per-field validation errors, present on 400 validation failures. items: type: object properties: field: type: string message: type: string reason: type: string description: >- Apple Ads query validation reason; unsupported_parameter for unknown/unsupported keys, invalid_parameter for malformed values or shapes. enum: - unsupported_parameter - invalid_parameter securitySchemes: secretAuth: type: http scheme: bearer bearerFormat: sk_… description: >- 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](/reference/v4/authentication). Never expose the Secret Key in client-side code. actorAssertionAuth: type: apiKey in: header name: X-Qonversion-Actor-Assertion description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.