Google Ads Incentives API

openapi: 3.2.0
info:
  title: Google Ads Incentives 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: incentives
paths:
  /v25/incentives:fetchIncentive:
    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.
    get:
      operationId: googleads_incentives_fetchIncentive
      summary: Returns incentives for a given user.
      tags:
      - incentives
      description: Returns incentives for a given user.
      parameters:
      - name: languageCode
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. User''s language code. If not provided, the server will default to "en". Possible language codes: https://developers.google.com/google-ads/api/data/codes-formats#languages'
      - name: countryCode
        in: query
        required: false
        schema:
          type: string
        description: 'Optional. User''s country code. If not provided, the server will default to "US". Possible country codes: https://developers.google.com/google-ads/api/data/codes-formats#country_codes'
      - name: email
        in: query
        required: false
        schema:
          type: string
        description: Optional. Email of the user that the requested incentive is meant for. Will be used for channel partners who do NOT use OAuth to authenticate on behalf of user.
      - name: incentiveType
        in: query
        required: false
        schema:
          x-enumDescriptions:
          - Not specified.
          - Unknown incentive type. Should not be used as a value explicitly.
          - An acquisition incentive.
          type: string
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - ACQUISITION
        description: Optional. The type of incentive to get. Defaults to ACQUISITION.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__FetchIncentiveResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/adwords
components:
  schemas:
    GoogleAdsGoogleadsV25Services_IncentiveRequirement_Spend:
      type: object
      properties:
        awardAmount:
          description: Required. Amount in free spend that user will be granted after spending target amount. Denominated in the currency of the country passed in the get request.
          $ref: '#/components/schemas/GoogleType__Money'
        requiredAmount:
          description: Required. Amount that user must spend to receive the award amount. Denominated in the currency of the country passed in the get request.
          $ref: '#/components/schemas/GoogleType__Money'
      description: Spend requirements for an incentive.
    GoogleAdsGoogleadsV25Services__CyoIncentives:
      type: object
      properties:
        mediumOffer:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__Incentive'
          description: Required. The CYO incentive with medium target and award amounts.
        lowOffer:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__Incentive'
          description: Required. The CYO incentive with low target and award amounts.
        highOffer:
          description: Required. The CYO incentive with high target and award amounts.
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__Incentive'
      description: An incentive offer in the Choose-Your-Own Incentive feature where a user can select from a set of incentives with different money amounts.
    GoogleAdsGoogleadsV25Services__IncentiveOffer:
      type: object
      properties:
        consolidatedTermsAndConditionsUrl:
          description: Optional. The URL of the terms and conditions for the incentive offer.
          type: string
        cyoIncentives:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__CyoIncentives'
          description: CYO incentives. Set when type is CYO_INCENTIVE.
        offerType:
          description: Required. The type of this acquisition incentive offer.
          type: string
          x-enumDescriptions:
          - Not specified.
          - Unknown offer type.
          - An offer with no incentive.
          - A CYO (Choose-Your-Own) offer with multiple incentives to choose from.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - NO_INCENTIVE
          - CYO_INCENTIVE
      description: An acquisition incentive offer for a user. An offer means how the user is treated. An offer can have no incentive or multiple incentives.
    GoogleType__Money:
      description: Represents an amount of money with its currency type.
      type: object
      properties:
        currencyCode:
          description: The three-letter currency code defined in ISO 4217.
          type: string
        nanos:
          format: int32
          description: Number of nano (10^-9) units of the amount. The value must be between -999,999,999 and +999,999,999 inclusive. If `units` is positive, `nanos` must be positive or zero. If `units` is zero, `nanos` can be positive, zero, or negative. If `units` is negative, `nanos` must be negative or zero. For example $-1.75 is represented as `units`=-1 and `nanos`=-750,000,000.
          type: integer
        units:
          description: The whole units of the amount. For example if `currencyCode` is `"USD"`, then 1 unit is one US dollar.
          type: string
          format: int64
    GoogleAdsGoogleadsV25Services__Incentive:
      description: An incentive that a user can claim for their account.
      type: object
      properties:
        requirement:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services_Incentive_Requirement'
          description: The requirement for this incentive.
        incentiveId:
          format: int64
          type: string
          description: The incentive ID of this incentive. This is used to identify which incentive is selected by the user in the CYO flow.
        incentiveTermsAndConditionsUrl:
          type: string
          description: The URL of the terms and conditions for THIS incentive offer ONLY. This is different from the terms_and_conditions_url field in AcquisitionIncentiveOffer which is a combination of all the Incentive offers in a CYO offer.
        incentiveType:
          description: The type of the incentive.
          type: string
          x-enumDescriptions:
          - Not specified.
          - Unknown incentive type. Should not be used as a value explicitly.
          - An acquisition incentive.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - ACQUISITION
    GoogleAdsGoogleadsV25Services_Incentive_Requirement:
      description: Requirement for an incentive.
      type: object
      properties:
        spend:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services_IncentiveRequirement_Spend'
          description: Optional. Spend requirement for an incentive.
    GoogleAdsGoogleadsV25Services__FetchIncentiveResponse:
      description: Response from getting the acquisition incentive for a user when they visit a specific marketing page.
      type: object
      properties:
        incentiveOffer:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__IncentiveOffer'
          description: Required. The acquisition incentive offer for the user.
  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