Google Ads Customers.recommendation Subscriptions API

openapi: 3.2.0
info:
  title: Google Ads Customers.recommendation Subscriptions API
  description: Manage your Google Ads accounts, campaigns, and reports with this API.
  version: v25
  x-discovery-revision: '20260721'
  contact:
    name: Google
    url: https://developers.google.com/google-ads/api/
  termsOfService: https://developers.google.com/terms
servers:
- url: https://googleads.googleapis.com
  description: Google Ads API production server
security:
- oauth2:
  - https://www.googleapis.com/auth/adwords
tags:
- name: customers.recommendationSubscriptions
paths:
  /v25/customers/{customersId}/recommendationSubscriptions:mutateRecommendationSubscription:
    parameters:
    - name: upload_protocol
      in: query
      required: false
      schema:
        type: string
      description: Upload protocol for media (e.g. "raw", "multipart").
    - name: quotaUser
      in: query
      required: false
      schema:
        type: string
      description: Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.
    - name: fields
      in: query
      required: false
      schema:
        type: string
      description: Selector specifying which fields to include in a partial response.
    - name: $.xgafv
      in: query
      required: false
      schema:
        type: string
        enum:
        - '1'
        - '2'
        x-enumDescriptions:
        - v1 error format
        - v2 error format
      description: V1 error format.
    - name: callback
      in: query
      required: false
      schema:
        type: string
      description: JSONP
    - name: prettyPrint
      in: query
      required: false
      schema:
        type: boolean
        default: 'true'
      description: Returns response with indentations and line breaks.
    - name: access_token
      in: query
      required: false
      schema:
        type: string
      description: OAuth access token.
    - name: uploadType
      in: query
      required: false
      schema:
        type: string
      description: Legacy upload protocol for media (e.g. "media", "multipart").
    - name: key
      in: query
      required: false
      schema:
        type: string
      description: API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.
    - name: oauth_token
      in: query
      required: false
      schema:
        type: string
      description: OAuth 2.0 token for the current user.
    - name: alt
      in: query
      required: false
      schema:
        x-enumDescriptions:
        - Responses with Content-Type of application/json
        - Media download with context-dependent Content-Type
        - Responses with Content-Type of application/x-protobuf
        type: string
        default: json
        enum:
        - json
        - media
        - proto
      description: Data format for response.
    post:
      operationId: googleads_customers_recommendationSubscriptions_mutateRecommendationSubscription
      summary: Mutates given subscription with corresponding apply parameters
      tags:
      - customers.recommendationSubscriptions
      description: 'Mutates given subscription with corresponding apply parameters. List of thrown errors: [AuthenticationError]() [AuthorizationError]() [DatabaseError]() [FieldError]() [HeaderError]() [InternalError]() [MutateError]() [QuotaError]() [RecommendationError]() [RecommendationSubscriptionError]() [RequestError]() [UrlFieldError]()'
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          pattern: ^[^/]+$
          type: string
        description: Required. The ID of the subscribing customer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__MutateRecommendationSubscriptionRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__MutateRecommendationSubscriptionResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/adwords
components:
  schemas:
    GoogleAdsGoogleadsV25Services__MutateRecommendationSubscriptionRequest:
      type: object
      properties:
        partialFailure:
          description: If true, successful operations will be carried out and invalid operations will return errors. If false, all operations will be carried out in one transaction if and only if they are all valid. Default is false.
          type: boolean
        operations:
          type: array
          description: Required. The list of create or update operations.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__RecommendationSubscriptionOperation'
        validateOnly:
          type: boolean
          description: If true, the request is validated but not executed. Only errors are returned, not results.
        responseContentType:
          x-enumDescriptions:
          - Not specified. Will return the resource name only in the response.
          - The mutate response will be the resource name.
          - The mutate response will contain the resource name and the resource with mutable fields if possible. Otherwise, only the resource name will be returned.
          enum:
          - UNSPECIFIED
          - RESOURCE_NAME_ONLY
          - MUTABLE_RESOURCE
          description: The response content type setting. Determines whether the mutable resource or just the resource name should be returned post mutation. The mutable resource will only be returned if the resource has the appropriate response field. For example, MutateCampaignResult.campaign.
          type: string
      description: Request message for RecommendationSubscriptionService.MutateRecommendationSubscription
    GoogleAdsGoogleadsV25Resources__RecommendationSubscription:
      description: Recommendation Subscription resource
      type: object
      properties:
        status:
          type: string
          description: Required. Status of the subscription, either enabled or paused.
          x-enumDescriptions:
          - Not specified.
          - Output-only. Represents a format not yet defined in this enum.
          - A subscription in the enabled state will automatically apply any recommendations of that type.
          - Recommendations of the relevant type will not be automatically applied. Subscriptions cannot be deleted. Once created, they can only move between enabled and paused states.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - ENABLED
          - PAUSED
        type:
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - Provides optimized budget recommendations for campaigns.
          - Keyword recommendation.
          - Recommendation to add a new text ad.
          - Recommendation to update a campaign to use a Target CPA bidding strategy.
          - Recommendation to update a campaign to use the Maximize Conversions bidding strategy.
          - Recommendation to enable Enhanced Cost Per Click for a campaign.
          - Recommendation to start showing your campaign's ads on Google Search Partners Websites.
          - Recommendation to update a campaign to use a Maximize Clicks bidding strategy.
          - Recommendation to start using the "Optimize" ad rotation setting for the given ad group.
          - Recommendation to change an existing keyword from one match type to a broader match type.
          - Recommendation to move unused budget from one budget to a constrained budget.
          - Budget recommendation for campaigns that are expected to become budget-constrained in the future (as opposed to the CAMPAIGN_BUDGET recommendation, which applies to campaigns that are currently budget-constrained).
          - Recommendation to update a campaign to use a Target ROAS bidding strategy.
          - Recommendation to add a new responsive search ad.
          - Budget recommendation for campaigns whose ROI is predicted to increase with a budget adjustment.
          - Recommendation to add broad match versions of keywords for fully automated conversion-based bidding campaigns.
          - Recommendation to add new responsive search ad assets.
          - Recommendation to upgrade a Smart Shopping campaign to a Performance Max campaign.
          - Recommendation to improve strength of responsive search ad.
          - Recommendation to update a campaign to use Display Expansion.
          - Recommendation to upgrade a Local campaign to a Performance Max campaign.
          - Recommendation to raise target CPA when it is too low and there are very few or no conversions. It is applied asynchronously and can take minutes depending on the number of ad groups there are in the related campaign.
          - Recommendation to raise the budget in advance of a seasonal event that is forecasted to increase traffic, and change bidding strategy from maximize conversion value to target ROAS.
          - Recommendation to add callout assets to campaign or customer level.
          - Recommendation to add sitelink assets to campaign or customer level.
          - Recommendation to add call assets to campaign or customer level.
          - Recommendation to add the age group attribute to offers that are demoted because of a missing age group.
          - Recommendation to add a color to offers that are demoted because of a missing color.
          - Recommendation to add a gender to offers that are demoted because of a missing gender.
          - Recommendation to add a GTIN (Global Trade Item Number) to offers that are demoted because of a missing GTIN.
          - Recommendation to add more identifiers to offers that are demoted because of missing identifiers.
          - Recommendation to add the size to offers that are demoted because of a missing size.
          - Recommendation informing a customer about a campaign that cannot serve because no products are being targeted.
          - The shopping recommendation informing a customer about campaign with a high percentage of disapproved products.
          - Recommendation to create a catch-all campaign that targets all offers.
          - Recommendation to fix Merchant Center account suspension issues.
          - Recommendation to fix Merchant Center account suspension warning issues.
          - Recommendation to migrate offers targeted by Regular Shopping Campaigns to existing Performance Max campaigns.
          - Recommendation to enable dynamic image extensions on the account, allowing Google to find the best images from ad landing pages and complement text ads.
          - Recommendation to raise Target CPA based on Google predictions modeled from past conversions. It is applied asynchronously and can take minutes depending on the number of ad groups there are in the related campaign.
          - Recommendation to lower Target ROAS.
          - Recommendation to opt into Performance Max campaigns.
          - Recommendation to improve the asset group strength of a Performance Max campaign to an "Excellent" rating.
          - Recommendation to migrate Dynamic Search Ads to Performance Max campaigns.
          - Recommendation to set a target CPA for campaigns that do not have one specified, in advance of a seasonal event that is forecasted to increase traffic.
          - Recommendation to set a target CPA for campaigns that do not have one specified.
          - Recommendation to set a target ROAS for campaigns that do not have one specified.
          - Recommendation to update a campaign to use the Maximize Conversion Value bidding strategy.
          - Recommendation to deploy Google Tag on more pages.
          - Recommendation to turn on Final URL expansion for your Performance Max campaigns.
          - Recommendation to update a customer list that hasn't been updated in the last 90 days.
          - Recommendation to create a custom audience.
          - Recommendation to add lead form assets to campaign or customer level.
          - Recommendation to improve the strength of ads in Demand Gen campaigns.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - CAMPAIGN_BUDGET
          - KEYWORD
          - TEXT_AD
          - TARGET_CPA_OPT_IN
          - MAXIMIZE_CONVERSIONS_OPT_IN
          - ENHANCED_CPC_OPT_IN
          - SEARCH_PARTNERS_OPT_IN
          - MAXIMIZE_CLICKS_OPT_IN
          - OPTIMIZE_AD_ROTATION
          - KEYWORD_MATCH_TYPE
          - MOVE_UNUSED_BUDGET
          - FORECASTING_CAMPAIGN_BUDGET
          - TARGET_ROAS_OPT_IN
          - RESPONSIVE_SEARCH_AD
          - MARGINAL_ROI_CAMPAIGN_BUDGET
          - USE_BROAD_MATCH_KEYWORD
          - RESPONSIVE_SEARCH_AD_ASSET
          - UPGRADE_SMART_SHOPPING_CAMPAIGN_TO_PERFORMANCE_MAX
          - RESPONSIVE_SEARCH_AD_IMPROVE_AD_STRENGTH
          - DISPLAY_EXPANSION_OPT_IN
          - UPGRADE_LOCAL_CAMPAIGN_TO_PERFORMANCE_MAX
          - RAISE_TARGET_CPA_BID_TOO_LOW
          - FORECASTING_SET_TARGET_ROAS
          - CALLOUT_ASSET
          - SITELINK_ASSET
          - CALL_ASSET
          - SHOPPING_ADD_AGE_GROUP
          - SHOPPING_ADD_COLOR
          - SHOPPING_ADD_GENDER
          - SHOPPING_ADD_GTIN
          - SHOPPING_ADD_MORE_IDENTIFIERS
          - SHOPPING_ADD_SIZE
          - SHOPPING_ADD_PRODUCTS_TO_CAMPAIGN
          - SHOPPING_FIX_DISAPPROVED_PRODUCTS
          - SHOPPING_TARGET_ALL_OFFERS
          - SHOPPING_FIX_SUSPENDED_MERCHANT_CENTER_ACCOUNT
          - SHOPPING_FIX_MERCHANT_CENTER_ACCOUNT_SUSPENSION_WARNING
          - SHOPPING_MIGRATE_REGULAR_SHOPPING_CAMPAIGN_OFFERS_TO_PERFORMANCE_MAX
          - DYNAMIC_IMAGE_EXTENSION_OPT_IN
          - RAISE_TARGET_CPA
          - LOWER_TARGET_ROAS
          - PERFORMANCE_MAX_OPT_IN
          - IMPROVE_PERFORMANCE_MAX_AD_STRENGTH
          - MIGRATE_DYNAMIC_SEARCH_ADS_CAMPAIGN_TO_PERFORMANCE_MAX
          - FORECASTING_SET_TARGET_CPA
          - SET_TARGET_CPA
          - SET_TARGET_ROAS
          - MAXIMIZE_CONVERSION_VALUE_OPT_IN
          - IMPROVE_GOOGLE_TAG_COVERAGE
          - PERFORMANCE_MAX_FINAL_URL_OPT_IN
          - REFRESH_CUSTOMER_MATCH_LIST
          - CUSTOM_AUDIENCE_OPT_IN
          - LEAD_FORM_ASSET
          - IMPROVE_DEMAND_GEN_AD_STRENGTH
          description: Required. Immutable. The type of recommendation subscribed to.
          type: string
        createDateTime:
          type: string
          description: Output only. Time in seconds when the subscription was first created. The datetime is in the customer's time zone and in "yyyy-MM-dd HH:mm:ss" format.
        modifyDateTime:
          type: string
          description: Output only. Contains the time in microseconds, when the Recommendation Subscription was last updated. The datetime is in the customer's time zone and in "yyyy-MM-dd HH:mm:ss.ssssss" format.
        resourceName:
          description: Immutable. The resource name of the recommendation subscription. `customers/{customer_id}/recommendationSubscriptions/{recommendation_type}`
          type: string
    GoogleAdsGoogleadsV25Services__MutateRecommendationSubscriptionResult:
      type: object
      properties:
        resourceName:
          type: string
          description: Resource name of the subscription that was modified.
        recommendationSubscription:
          description: The mutated recommendation subscription with only mutable fields after mutate. The field will only be returned when response_content_type is set to "MUTABLE_RESOURCE".
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources__RecommendationSubscription'
      description: Result message for RecommendationSubscriptionService.MutateRecommendationSubscription
    GoogleRpc__Status:
      description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).'
      type: object
      properties:
        message:
          description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.
          type: string
        code:
          type: integer
          description: The status code, which should be an enum value of google.rpc.Code.
          format: int32
        details:
          type: array
          description: A list of messages that carry the error details. There is a common set of message types for APIs to use.
          items:
            type: object
            additionalProperties:
              description: Properties of the object. Contains field @type with type URL.
    GoogleAdsGoogleadsV25Services__MutateRecommendationSubscriptionResponse:
      type: object
      properties:
        partialFailureError:
          description: Errors that pertain to operation failures in the partial failure mode. Returned only when partial_failure = true and all errors occur inside the operations. If any errors occur outside the operations (for example, auth errors) we return the RPC level error.
          $ref: '#/components/schemas/GoogleRpc__Status'
        results:
          description: Results, one per operation.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__MutateRecommendationSubscriptionResult'
          type: array
      description: Response message for RecommendationSubscriptionService.MutateRecommendationSubscription
    GoogleAdsGoogleadsV25Services__RecommendationSubscriptionOperation:
      type: object
      properties:
        update:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources__RecommendationSubscription'
          description: 'Update operation: The subscription is expected to have a valid resource name.'
        updateMask:
          format: google-fieldmask
          description: Optional. FieldMask that determines which resource fields are modified in an update.
          type: string
        create:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources__RecommendationSubscription'
          description: 'Create operation: No resource name is expected for the new subscription.'
      description: A single operation (create, update) on a recommendation subscription. RecommendationSubscriptionService.MutateRecommendationSubscription
  securitySchemes:
    oauth2:
      type: oauth2
      description: Google OAuth 2.0. Google Ads API additionally requires a developer token in the developer-token header.
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/adwords: See, edit, create, and delete your Google Ads accounts and data.
externalDocs:
  url: https://developers.google.com/google-ads/api/
x-source: https://googleads.googleapis.com/$discovery/rest?version=v25
x-generated-by: API Evangelist enrichment pipeline — mechanical conversion of the first-party Google API Discovery Document