<!--
{
  "availability" : [
    "Apple Ads Platform API: 1.0.0 -"
  ],
  "documentType" : "article",
  "framework" : "Apple-Ads-Platform-API",
  "identifier" : "/documentation/Apple-Ads-Platform-API/recommendations-endpoints",
  "metadataVersion" : "0.1.0",
  "role" : "collectionGroup",
  "title" : "Recommendations Endpoints"
}
-->

# Recommendations Endpoints

Endpoints for querying, applying, and dismissing budget and Target CPA recommendations.

## Overview

The Recommendations API returns recommendations for target CPA adjustments and daily budget increases to help you improve your campaigns’ performance. Unlike [Suggestions Endpoints](/documentation/Apple-Ads-Platform-API/suggestions-endpoints), recommendations are stateful; each one has a lifecycle you apply or dismiss, and the system tracks the outcome. For historical performance metrics, see [Managing Reports](/documentation/Apple-Ads-Platform-API/reports). For market-level signals like impression share, see [Insights Endpoints](/documentation/Apple-Ads-Platform-API/insights-endpoints).

## Explore the Available Endpoints

The API scopes recommendations to a promoted object, either an app or a brand, that you identify by `promotedObjectId` and `promotedObjectType`. For `promotedObjectId`, use the app Adam ID when `promotedObjectType` is `APPSTORE_APP` and the brand ID when it’s `BUSINESS_BRAND`. Use `campaignId` as an optional filter to narrow results to a specific campaign.

For Apple Maps (`BUSINESS_BRAND`) campaigns, only daily budget recommendations are available. Target CPA recommendations apply to App Store (`APPSTORE_APP`) campaigns using a Maximize Conversions bid strategy, which relies on Search Match within the Search results placement.

The following endpoints let you query, apply, and dismiss recommendations:

|Method|Path                                       |Description                                                                                                                                                                                                                                                                                                                                                      |
|------|-------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`POST`|`/v1/recommendations/daily-budgets/query`  |Returns daily budget recommendations using <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/Query-daily-budget-recommendations>. Recommends an increased daily budget for campaigns that may have more opportunities, and includes historical and expected performance metrics.                                                      |
|`POST`|`/v1/recommendations/daily-budgets/apply`  |Applies a daily budget recommendation using <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/Apply-daily-budget-recommendations> and updates the campaign’s daily budget.                                                                                                                                                            |
|`POST`|`/v1/recommendations/daily-budgets/dismiss`|Dismisses a daily budget recommendation using <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/Dismiss-daily-budget-recommendations>.                                                                                                                                                                                                |
|`POST`|`/v1/recommendations/target-cpas/query`    |Returns target CPA recommendations using <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/Query-target-CPA-recommendations>. Recommends an adjusted target cost-per-acquisition for campaigns using a Maximize Conversions bid strategy. The system sets bids automatically to try to meet the target; the target itself isn’t a bid.|
|`POST`|`/v1/recommendations/target-cpas/apply`    |Applies a target CPA recommendation using <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/Apply-target-CPA-recommendations>.                                                                                                                                                                                                        |
|`POST`|`/v1/recommendations/target-cpas/dismiss`  |Dismisses a target CPA recommendation using <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/Dismiss-target-CPA-recommendations>.                                                                                                                                                                                                    |

### Track the Recommendation Lifecycle

Every recommendation has a `state` field. Recommendations start in `AVAILABLE` state and move to either `APPLIED` or `DISMISSED` via the API. State is terminal. After the system applies or dismisses a recommendation, it doesn’t return to available.

The `state` field tracks the advertiser’s response. New recommendations start `AVAILABLE`, then move to `APPLIED` or `DISMISSED`. The `status` field reflects whether the system marks the recommendation record itself `ENABLED`, `DISABLED`, or `DELETED`. In most workflows, only `state` matters.

The following table lists the possible `state` values:

|State      |Meaning                                                                                                |
|-----------|-------------------------------------------------------------------------------------------------------|
|`AVAILABLE`|The recommendation is active and awaiting action. This is the default state for new recommendations.   |
|`APPLIED`  |The advertiser accepted the recommendation, and the system made the change to the campaign or ad group.|
|`DISMISSED`|The advertiser explicitly rejected the recommendation. The system made no change to the campaign.      |
|`DELETE`   |The system archives the recommendation and no longer returns it in queries.                            |

> Note: The `DELETE` value of `state` and the `DELETED` value of `status` are similarly named but distinct. Don’t confuse them when filtering or reading a recommendation record.

### Recommendation Category

Every recommendation read object carries a `recommendationType` field using the [`RecommendationCategory`](/documentation/Apple-Ads-Platform-API/RecommendationCategory) enum. Each optimization area has a merged category and a system category (algorithm-generated, prefixed `S`). This field isn’t a filterable field on the query endpoints below; see each endpoint’s Filterable Fields table for what you can query on.

The following table lists each optimization area’s merged and system categories:

|Merged    |System (S) |Applies To                  |
|----------|-----------|----------------------------|
|`DAILYCAP`|`SDAILYCAP`|Daily budget recommendations|
|`TCPA`    |`STCPA`    |Target CPA recommendations  |
|`BID`     |`SBID`     |Bid recommendations         |

Only `DAILYCAP` and `TCPA` have corresponding query, apply, and dismiss endpoints in this API version. `BID` is defined in the enum but has no dedicated endpoints.

### Query Recommendations

All recommendation types use a `POST /query` pattern with the [`RecommendationQueryRequest`](/documentation/Apple-Ads-Platform-API/RecommendationQueryRequest) body. Two filters are mandatory on every request:

- The `promotedObjectId` field is the ID of the promoted object being queried. Use the app Adam ID when `promotedObjectType` is `APPSTORE_APP`, or the brand ID when it’s `BUSINESS_BRAND`.
- The `promotedObjectType` field is the type of the promoted object (for example, `APPSTORE_APP`).

Optional filters such as `state` and `campaignId` narrow results further. The following example shows a query request body with these filters applied:

```json
{
  "pagination": {
    "offset": 0,
    "pageSize": 20
  },
  "filters": [
    {
      "field": "promotedObjectId",
      "operator": "EQUALS",
      "value": [
        "123456"
      ]
    },
    {
      "field": "promotedObjectType",
      "operator": "EQUALS",
      "value": [
        "APPSTORE_APP"
      ]
    },
    {
      "field": "state",
      "operator": "EQUALS",
      "value": [
        "AVAILABLE"
      ]
    }
  ],
  "sorting": [
    {
      "field": "creationTime",
      "order": "DESC"
    }
  ]
}
```

### Apply Recommendations

Applying a recommendation signals that the API user accepts the recommendation and wants the API to make the corresponding change automatically. Each type has a dedicated apply endpoint. All items in a single request must share the same `promotedObjectId`.

The following table shows what each apply endpoint changes:

|Endpoint                                 |Action Taken                                                                                                                                                                                   |
|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`/v1/recommendations/daily-budgets/apply`|Updates the campaign’s daily budget. See <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/Campaign/DailyBudget-data.dictionary>.                                   |
|`/v1/recommendations/target-cpas/apply`  |Updates the target CPA the campaign’s Maximize Conversions auto-bidding uses. This isn’t a field on Campaign or AdGroup. The applied value is only visible in this endpoint’s history response.|

Required fields on every apply item are `id`, `promotedObjectId`, and `promotedObjectType`.

### Dismiss Recommendations

Dismiss requests use the same structure as apply, but the API ignores value override fields. You only need `id`, `promotedObjectId`, and `promotedObjectType`. The request doesn’t modify any campaign or ad group entity.

### Review Recommendation History

Apply and dismiss operations return a history object rather than the original recommendation object. History records preserve the full state of the recommendation at the time of the action, including the value the system actually applied, and serve as the audit trail for optimization changes.

## Topics

[`Query Target CPA Recommendations`](/documentation/Apple-Ads-Platform-API/Query-target-CPA-recommendations)

[`Apply Target CPA Recommendations`](/documentation/Apple-Ads-Platform-API/Apply-target-CPA-recommendations)

[`Dismiss Target CPA Recommendations`](/documentation/Apple-Ads-Platform-API/Dismiss-target-CPA-recommendations)

[`Query Daily Budget Recommendations`](/documentation/Apple-Ads-Platform-API/Query-daily-budget-recommendations)

[`Apply Daily Budget Recommendations`](/documentation/Apple-Ads-Platform-API/Apply-daily-budget-recommendations)

[`Dismiss Daily Budget Recommendations`](/documentation/Apple-Ads-Platform-API/Dismiss-daily-budget-recommendations)

## See Also

[Suggestions Endpoints](/documentation/Apple-Ads-Platform-API/suggestions-endpoints)

Endpoints for querying keyword, phrase, category, and Target CPA suggestions.

[Managing Reports](/documentation/Apple-Ads-Platform-API/reports)

Retrieve performance data for campaigns, ad groups, ads, keywords, and search terms.

[Insights Endpoints](/documentation/Apple-Ads-Platform-API/insights-endpoints)

Query impression share and search term popularity data for your apps.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)