Google Ads Customers.account Budget Proposals API

openapi: 3.2.0
info:
  title: Google Ads Customers.account Budget Proposals 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.accountBudgetProposals
paths:
  /v25/customers/{customersId}/accountBudgetProposals:mutate:
    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_accountBudgetProposals_mutate
      summary: Creates, updates, or removes account budget proposals
      tags:
      - customers.accountBudgetProposals
      description: 'Creates, updates, or removes account budget proposals. Operation statuses are returned. List of thrown errors: [AccountBudgetProposalError]() [AuthenticationError]() [AuthorizationError]() [DatabaseError]() [DateError]() [FieldError]() [FieldMaskError]() [HeaderError]() [InternalError]() [MutateError]() [QuotaError]() [RequestError]() [StringLengthError]()'
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
          pattern: ^[^/]+$
        description: Required. The ID of the customer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__MutateAccountBudgetProposalRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__MutateAccountBudgetProposalResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/adwords
components:
  schemas:
    GoogleAdsGoogleadsV25Services__MutateAccountBudgetProposalRequest:
      type: object
      properties:
        operation:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__AccountBudgetProposalOperation'
          description: Required. The operation to perform on an individual account-level budget proposal.
        validateOnly:
          description: If true, the request is validated but not executed. Only errors are returned, not results.
          type: boolean
      description: Request message for AccountBudgetProposalService.MutateAccountBudgetProposal.
    GoogleAdsGoogleadsV25Services__MutateAccountBudgetProposalResult:
      description: The result for the account budget proposal mutate.
      type: object
      properties:
        resourceName:
          type: string
          description: Returned for successful operations.
    GoogleAdsGoogleadsV25Resources__AccountBudgetProposal:
      description: An account-level budget proposal. All fields prefixed with 'proposed' may not necessarily be applied directly. For example, proposed spending limits may be adjusted before their application. This is true if the 'proposed' field has an 'approved' counterpart, for example, spending limits. Note that the proposal type (proposal_type) changes which fields are required and which must remain empty.
      type: object
      properties:
        proposedName:
          type: string
          description: Immutable. The name to assign to the account-level budget.
        proposedEndTimeType:
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - As soon as possible.
          - An infinite point in the future.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - NOW
          - FOREVER
          description: Immutable. The proposed end date time as a well-defined type, for example, FOREVER.
          type: string
        proposedSpendingLimitMicros:
          format: int64
          description: Immutable. The proposed spending limit in micros. One million is equivalent to one unit.
          type: string
        billingSetup:
          description: Immutable. The resource name of the billing setup associated with this proposal.
          type: string
        proposedEndDateTime:
          description: Immutable. The proposed end date time in yyyy-mm-dd hh:mm:ss format.
          type: string
        approvedEndDateTime:
          type: string
          description: Output only. The approved end date time in yyyy-mm-dd hh:mm:ss format.
        approvedSpendingLimitType:
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - Infinite, indicates unlimited spending power.
          type: string
          description: Output only. The approved spending limit as a well-defined type, for example, INFINITE.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - INFINITE
        proposedStartDateTime:
          type: string
          description: Immutable. The proposed start date time in yyyy-mm-dd hh:mm:ss format.
        proposedPurchaseOrderNumber:
          type: string
          description: Immutable. A purchase order number is a value that enables the user to help them reference this budget in their monthly invoices.
        resourceName:
          description: 'Immutable. The resource name of the proposal. AccountBudgetProposal resource names have the form: `customers/{customer_id}/accountBudgetProposals/{account_budget_proposal_id}`'
          type: string
        id:
          format: int64
          description: Output only. The ID of the proposal.
          type: string
        proposedStartTimeType:
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - As soon as possible.
          - An infinite point in the future.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - NOW
          - FOREVER
          description: Immutable. The proposed start date time as a well-defined type, for example, NOW.
          type: string
        proposedSpendingLimitType:
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - Infinite, indicates unlimited spending power.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - INFINITE
          type: string
          description: Immutable. The proposed spending limit as a well-defined type, for example, INFINITE.
        approvedStartDateTime:
          type: string
          description: Output only. The approved start date time in yyyy-mm-dd hh:mm:ss format.
        accountBudget:
          type: string
          description: Immutable. The resource name of the account-level budget associated with this proposal.
        proposalType:
          type: string
          description: Immutable. The type of this proposal, for example, END to end the budget associated with this proposal.
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - Identifies a request to create a new budget.
          - Identifies a request to edit an existing budget.
          - Identifies a request to end a budget that has already started.
          - Identifies a request to remove a budget that hasn't started yet.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - CREATE
          - UPDATE
          - END
          - REMOVE
        proposedNotes:
          type: string
          description: Immutable. Notes associated with this budget.
        creationDateTime:
          description: Output only. The date time when this account-level budget proposal was created, which is not the same as its approval date time, if applicable.
          type: string
        approvalDateTime:
          description: Output only. The date time when this account-level budget was approved, if applicable.
          type: string
        approvedSpendingLimitMicros:
          description: Output only. The approved spending limit in micros. One million is equivalent to one unit.
          type: string
          format: int64
        status:
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - PENDING
          - APPROVED_HELD
          - APPROVED
          - CANCELLED
          - REJECTED
          description: Output only. The status of this proposal. When a new proposal is created, the status defaults to PENDING.
          type: string
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - The proposal is pending approval.
          - The proposal has been approved but the corresponding billing setup has not. This can occur for proposals that set up the first budget when signing up for billing or when performing a change of bill-to operation.
          - The proposal has been approved.
          - The proposal has been cancelled by the user.
          - The proposal has been rejected by the user, for example, by rejecting an acceptance email.
        approvedEndTimeType:
          description: Output only. The approved end date time as a well-defined type, for example, FOREVER.
          type: string
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - NOW
          - FOREVER
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - As soon as possible.
          - An infinite point in the future.
    GoogleAdsGoogleadsV25Services__AccountBudgetProposalOperation:
      description: A single operation to propose the creation of a new account-level budget or edit/end/remove an existing one.
      type: object
      properties:
        updateMask:
          description: FieldMask that determines which budget fields are modified. While budgets may be modified, proposals that propose such modifications are final. Therefore, update operations are not supported for proposals. Proposals that modify budgets have the 'update' proposal type. Specifying a mask for any other proposal type is considered an error.
          type: string
          format: google-fieldmask
        create:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources__AccountBudgetProposal'
          description: 'Create operation: A new proposal to create a new budget, edit an existing budget, end an actively running budget, or remove an approved budget scheduled to start in the future. No resource name is expected for the new proposal.'
        remove:
          type: string
          description: 'Remove operation: A resource name for the removed proposal is expected, in this format: `customers/{customer_id}/accountBudgetProposals/{account_budget_proposal_id}` A request may be cancelled iff it is pending.'
    GoogleAdsGoogleadsV25Services__MutateAccountBudgetProposalResponse:
      description: Response message for account-level budget mutate operations.
      type: object
      properties:
        result:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__MutateAccountBudgetProposalResult'
          description: The result of the mutate.
  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