--- title: Recommendations Endpoints framework: Apple Ads Platform API role: collectionGroup role_heading: API Collection platforms: [apple ads platform api 1.0+] path: apple-ads-platform-api/recommendations-endpoints --- # Recommendations Endpoints Endpoints for querying, applying, and dismissing budget and Target CPA recommendations. ## Overview Overview The Recommendations API returns recommendations for target CPA adjustments and daily budget increases to help you improve your campaigns’ performance. Unlike 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. For market-level signals like impression share, see 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: | | | | | | | | | | | | | | 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: | | | | | 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 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: | | | | | | | | 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 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: { "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: | | | 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](apple-ads-platform-api/query-target-cpa-recommendations.md) - [Apply Target CPA Recommendations](apple-ads-platform-api/apply-target-cpa-recommendations.md) - [Dismiss Target CPA Recommendations](apple-ads-platform-api/dismiss-target-cpa-recommendations.md) - [Query Daily Budget Recommendations](apple-ads-platform-api/query-daily-budget-recommendations.md) - [Apply Daily Budget Recommendations](apple-ads-platform-api/apply-daily-budget-recommendations.md) - [Dismiss Daily Budget Recommendations](apple-ads-platform-api/dismiss-daily-budget-recommendations.md) ## See Also ### Related Documentation - [Suggestions Endpoints](apple-ads-platform-api/suggestions-endpoints.md) - [Managing Reports](apple-ads-platform-api/reports.md) - [Insights Endpoints](apple-ads-platform-api/insights-endpoints.md) ### Recommendations - [Recommendations Data Objects](apple-ads-platform-api/recommendations-data-objects.md) - [Recommendations Query and Filter Objects](apple-ads-platform-api/recommendations-query-filter-objects.md)