1// Copyright 2023 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.ads.googleads.v14.resources; 18 19import "google/ads/googleads/v14/enums/account_budget_proposal_type.proto"; 20import "google/ads/googleads/v14/enums/account_budget_status.proto"; 21import "google/ads/googleads/v14/enums/spending_limit_type.proto"; 22import "google/ads/googleads/v14/enums/time_type.proto"; 23import "google/api/field_behavior.proto"; 24import "google/api/resource.proto"; 25 26option csharp_namespace = "Google.Ads.GoogleAds.V14.Resources"; 27option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v14/resources;resources"; 28option java_multiple_files = true; 29option java_outer_classname = "AccountBudgetProto"; 30option java_package = "com.google.ads.googleads.v14.resources"; 31option objc_class_prefix = "GAA"; 32option php_namespace = "Google\\Ads\\GoogleAds\\V14\\Resources"; 33option ruby_package = "Google::Ads::GoogleAds::V14::Resources"; 34 35// Proto file describing the AccountBudget resource. 36 37// An account-level budget. It contains information about the budget itself, 38// as well as the most recently approved changes to the budget and proposed 39// changes that are pending approval. The proposed changes that are pending 40// approval, if any, are found in 'pending_proposal'. Effective details about 41// the budget are found in fields prefixed 'approved_', 'adjusted_' and those 42// without a prefix. Since some effective details may differ from what the user 43// had originally requested (for example, spending limit), these differences are 44// juxtaposed through 'proposed_', 'approved_', and possibly 'adjusted_' fields. 45// 46// This resource is mutated using AccountBudgetProposal and cannot be mutated 47// directly. A budget may have at most one pending proposal at any given time. 48// It is read through pending_proposal. 49// 50// Once approved, a budget may be subject to adjustments, such as credit 51// adjustments. Adjustments create differences between the 'approved' and 52// 'adjusted' fields, which would otherwise be identical. 53message AccountBudget { 54 option (google.api.resource) = { 55 type: "googleads.googleapis.com/AccountBudget" 56 pattern: "customers/{customer_id}/accountBudgets/{account_budget_id}" 57 }; 58 59 // A pending proposal associated with the enclosing account-level budget, 60 // if applicable. 61 message PendingAccountBudgetProposal { 62 // Output only. The resource name of the proposal. 63 // AccountBudgetProposal resource names have the form: 64 // 65 // `customers/{customer_id}/accountBudgetProposals/{account_budget_proposal_id}` 66 optional string account_budget_proposal = 12 [ 67 (google.api.field_behavior) = OUTPUT_ONLY, 68 (google.api.resource_reference) = { 69 type: "googleads.googleapis.com/AccountBudgetProposal" 70 } 71 ]; 72 73 // Output only. The type of this proposal, for example, END to end the 74 // budget associated with this proposal. 75 google.ads.googleads.v14.enums.AccountBudgetProposalTypeEnum 76 .AccountBudgetProposalType proposal_type = 2 77 [(google.api.field_behavior) = OUTPUT_ONLY]; 78 79 // Output only. The name to assign to the account-level budget. 80 optional string name = 13 [(google.api.field_behavior) = OUTPUT_ONLY]; 81 82 // Output only. The start time in yyyy-MM-dd HH:mm:ss format. 83 optional string start_date_time = 14 84 [(google.api.field_behavior) = OUTPUT_ONLY]; 85 86 // Output only. A purchase order number is a value that helps users 87 // reference this budget in their monthly invoices. 88 optional string purchase_order_number = 17 89 [(google.api.field_behavior) = OUTPUT_ONLY]; 90 91 // Output only. Notes associated with this budget. 92 optional string notes = 18 [(google.api.field_behavior) = OUTPUT_ONLY]; 93 94 // Output only. The time when this account-level budget proposal was 95 // created. Formatted as yyyy-MM-dd HH:mm:ss. 96 optional string creation_date_time = 19 97 [(google.api.field_behavior) = OUTPUT_ONLY]; 98 99 // The end time of the account-level budget. 100 oneof end_time { 101 // Output only. The end time in yyyy-MM-dd HH:mm:ss format. 102 string end_date_time = 15 [(google.api.field_behavior) = OUTPUT_ONLY]; 103 104 // Output only. The end time as a well-defined type, for example, FOREVER. 105 google.ads.googleads.v14.enums.TimeTypeEnum.TimeType end_time_type = 6 106 [(google.api.field_behavior) = OUTPUT_ONLY]; 107 } 108 109 // The spending limit. 110 oneof spending_limit { 111 // Output only. The spending limit in micros. One million is equivalent 112 // to one unit. 113 int64 spending_limit_micros = 16 114 [(google.api.field_behavior) = OUTPUT_ONLY]; 115 116 // Output only. The spending limit as a well-defined type, for example, 117 // INFINITE. 118 google.ads.googleads.v14.enums.SpendingLimitTypeEnum.SpendingLimitType 119 spending_limit_type = 8 [(google.api.field_behavior) = OUTPUT_ONLY]; 120 } 121 } 122 123 // Output only. The resource name of the account-level budget. 124 // AccountBudget resource names have the form: 125 // 126 // `customers/{customer_id}/accountBudgets/{account_budget_id}` 127 string resource_name = 1 [ 128 (google.api.field_behavior) = OUTPUT_ONLY, 129 (google.api.resource_reference) = { 130 type: "googleads.googleapis.com/AccountBudget" 131 } 132 ]; 133 134 // Output only. The ID of the account-level budget. 135 optional int64 id = 23 [(google.api.field_behavior) = OUTPUT_ONLY]; 136 137 // Output only. The resource name of the billing setup associated with this 138 // account-level budget. BillingSetup resource names have the form: 139 // 140 // `customers/{customer_id}/billingSetups/{billing_setup_id}` 141 optional string billing_setup = 24 [ 142 (google.api.field_behavior) = OUTPUT_ONLY, 143 (google.api.resource_reference) = { 144 type: "googleads.googleapis.com/BillingSetup" 145 } 146 ]; 147 148 // Output only. The status of this account-level budget. 149 google.ads.googleads.v14.enums.AccountBudgetStatusEnum.AccountBudgetStatus 150 status = 4 [(google.api.field_behavior) = OUTPUT_ONLY]; 151 152 // Output only. The name of the account-level budget. 153 optional string name = 25 [(google.api.field_behavior) = OUTPUT_ONLY]; 154 155 // Output only. The proposed start time of the account-level budget in 156 // yyyy-MM-dd HH:mm:ss format. If a start time type of NOW was proposed, 157 // this is the time of request. 158 optional string proposed_start_date_time = 26 159 [(google.api.field_behavior) = OUTPUT_ONLY]; 160 161 // Output only. The approved start time of the account-level budget in 162 // yyyy-MM-dd HH:mm:ss format. 163 // 164 // For example, if a new budget is approved after the proposed start time, 165 // the approved start time is the time of approval. 166 optional string approved_start_date_time = 27 167 [(google.api.field_behavior) = OUTPUT_ONLY]; 168 169 // Output only. The total adjustments amount. 170 // 171 // An example of an adjustment is courtesy credits. 172 int64 total_adjustments_micros = 33 173 [(google.api.field_behavior) = OUTPUT_ONLY]; 174 175 // Output only. The value of Ads that have been served, in micros. 176 // 177 // This includes overdelivery costs, in which case a credit might be 178 // automatically applied to the budget (see total_adjustments_micros). 179 int64 amount_served_micros = 34 [(google.api.field_behavior) = OUTPUT_ONLY]; 180 181 // Output only. A purchase order number is a value that helps users reference 182 // this budget in their monthly invoices. 183 optional string purchase_order_number = 35 184 [(google.api.field_behavior) = OUTPUT_ONLY]; 185 186 // Output only. Notes associated with the budget. 187 optional string notes = 36 [(google.api.field_behavior) = OUTPUT_ONLY]; 188 189 // Output only. The pending proposal to modify this budget, if applicable. 190 PendingAccountBudgetProposal pending_proposal = 22 191 [(google.api.field_behavior) = OUTPUT_ONLY]; 192 193 // The proposed end time of the account-level budget. 194 oneof proposed_end_time { 195 // Output only. The proposed end time in yyyy-MM-dd HH:mm:ss format. 196 string proposed_end_date_time = 28 197 [(google.api.field_behavior) = OUTPUT_ONLY]; 198 199 // Output only. The proposed end time as a well-defined type, for example, 200 // FOREVER. 201 google.ads.googleads.v14.enums.TimeTypeEnum.TimeType 202 proposed_end_time_type = 9 [(google.api.field_behavior) = OUTPUT_ONLY]; 203 } 204 205 // The approved end time of the account-level budget. 206 // 207 // For example, if a budget's end time is updated and the proposal is approved 208 // after the proposed end time, the approved end time is the time of approval. 209 oneof approved_end_time { 210 // Output only. The approved end time in yyyy-MM-dd HH:mm:ss format. 211 string approved_end_date_time = 29 212 [(google.api.field_behavior) = OUTPUT_ONLY]; 213 214 // Output only. The approved end time as a well-defined type, for example, 215 // FOREVER. 216 google.ads.googleads.v14.enums.TimeTypeEnum.TimeType 217 approved_end_time_type = 11 [(google.api.field_behavior) = OUTPUT_ONLY]; 218 } 219 220 // The proposed spending limit. 221 oneof proposed_spending_limit { 222 // Output only. The proposed spending limit in micros. One million is 223 // equivalent to one unit. 224 int64 proposed_spending_limit_micros = 30 225 [(google.api.field_behavior) = OUTPUT_ONLY]; 226 227 // Output only. The proposed spending limit as a well-defined type, for 228 // example, INFINITE. 229 google.ads.googleads.v14.enums.SpendingLimitTypeEnum.SpendingLimitType 230 proposed_spending_limit_type = 13 231 [(google.api.field_behavior) = OUTPUT_ONLY]; 232 } 233 234 // The approved spending limit. 235 // 236 // For example, if the amount already spent by the account exceeds the 237 // proposed spending limit at the time the proposal is approved, the approved 238 // spending limit is set to the amount already spent. 239 oneof approved_spending_limit { 240 // Output only. The approved spending limit in micros. One million is 241 // equivalent to one unit. This will only be populated if the proposed 242 // spending limit is finite, and will always be greater than or equal to the 243 // proposed spending limit. 244 int64 approved_spending_limit_micros = 31 245 [(google.api.field_behavior) = OUTPUT_ONLY]; 246 247 // Output only. The approved spending limit as a well-defined type, for 248 // example, INFINITE. This will only be populated if the approved spending 249 // limit is INFINITE. 250 google.ads.googleads.v14.enums.SpendingLimitTypeEnum.SpendingLimitType 251 approved_spending_limit_type = 15 252 [(google.api.field_behavior) = OUTPUT_ONLY]; 253 } 254 255 // The spending limit after adjustments have been applied. Adjustments are 256 // stored in total_adjustments_micros. 257 // 258 // This value has the final say on how much the account is allowed to spend. 259 oneof adjusted_spending_limit { 260 // Output only. The adjusted spending limit in micros. One million is 261 // equivalent to one unit. 262 // 263 // If the approved spending limit is finite, the adjusted 264 // spending limit may vary depending on the types of adjustments applied 265 // to this budget, if applicable. 266 // 267 // The different kinds of adjustments are described here: 268 // https://support.google.com/google-ads/answer/1704323 269 // 270 // For example, a debit adjustment reduces how much the account is 271 // allowed to spend. 272 int64 adjusted_spending_limit_micros = 32 273 [(google.api.field_behavior) = OUTPUT_ONLY]; 274 275 // Output only. The adjusted spending limit as a well-defined type, for 276 // example, INFINITE. This will only be populated if the adjusted spending 277 // limit is INFINITE, which is guaranteed to be true if the approved 278 // spending limit is INFINITE. 279 google.ads.googleads.v14.enums.SpendingLimitTypeEnum.SpendingLimitType 280 adjusted_spending_limit_type = 17 281 [(google.api.field_behavior) = OUTPUT_ONLY]; 282 } 283} 284