feat: update products_common fields to include handling_cutoff_timezone , shipping_handling_business_days, shipping_transit_business_days

Google APIs · copybara-github · commit 256b575f6915 · 2026-03-11T01:52:53.000-07:00
docs: comment for messages for products_common are changed
PiperOrigin-RevId: 881874426
diff --git a/google/shopping/merchant/products/v1/productinputs.proto b/google/shopping/merchant/products/v1/productinputs.proto
@@ -1,4 +1,4 @@
-// Copyright 2025 Google LLC
+// Copyright 2026 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -39,11 +39,11 @@ service ProductInputsService {
   option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/content";
 
   // [Uploads a product input to your Merchant Center
-  // account](/merchant/api/guides/products/overview#upload-product-input). You
+  // account](/merchant/api/guides/products/add-manage#add_a_product). You
   // must have a products [data
-  // source](/merchant/api/guides/data-sources/overview) to be able to insert a
-  // product. The unique identifier of the data source is passed as a query
-  // parameter in the request URL.
+  // source](/merchant/api/guides/data-sources/api-sources#create-primary-data-source)
+  // to be able to insert a product. The unique identifier of the data source is
+  // passed as a query parameter in the request URL.
   //
   // If a product input with the same contentLanguage, offerId, and dataSource
   // already exists, then the product input inserted by this method replaces
@@ -59,6 +59,8 @@ service ProductInputsService {
   }
 
   // Updates the existing product input in your Merchant Center account.
+  // The name of the product input to update is taken from the `name` field
+  // within the `ProductInput` resource.
   //
   // After inserting, updating, or deleting a product input, it may take several
   // minutes before the processed product can be retrieved.
@@ -117,16 +119,44 @@ message ProductInput {
     singular: "productInput"
   };
 
-  // Identifier. The name of the product input.
+  // Identifier. The name of the product.
   // Format: `accounts/{account}/productInputs/{productinput}`
-  // where the last section `productinput` consists of:
-  // `content_language~feed_label~offer_id`
-  // example for product input name is
-  // `accounts/123/productInputs/en~US~sku123`. A legacy local product input
-  // name would be `accounts/123/productInputs/local~en~US~sku123`.
-  // Note: For calls to the v1beta version, the `productInput` section consists
-  // of: `channel~content_language~feed_label~offer_id`, for example:
-  // `accounts/123/productInputs/online~en~US~sku123`.
+  //
+  // The {productinput} segment is a unique identifier for the product.
+  // This identifier must be unique within a merchant account and generally
+  // follows the structure: `content_language~feed_label~offer_id`. Example:
+  // `en~US~sku123` For legacy local products, the structure is:
+  // `local~content_language~feed_label~offer_id`. Example: `local~en~US~sku123`
+  //
+  // The format of the {productinput} segment in the URL is automatically
+  // detected by the server, supporting two options:
+  //
+  // 1.  **Encoded Format**: The `{productinput}` segment is an unpadded
+  // base64url
+  //     encoded string (RFC 4648 Section 5). The decoded string must result
+  //     in the `content_language~feed_label~offer_id` structure. This encoding
+  //     MUST be used if any part of the product identifier (like `offer_id`)
+  //     contains characters such as `/`, `%`, or `~`.
+  //     *   Example: To represent the product ID `en~US~sku/123`, the
+  //         `{productinput}` segment must be the base64url encoding of this
+  //         string, which is `ZW5-VVMtc2t1LzEyMw`. The full resource name
+  //         for the product would be
+  //         `accounts/123/productinputs/ZW5-VVMtc2t1LzEyMw`.
+  //
+  // 2.  **Plain Format**: The `{productinput}` segment is the tilde-separated
+  // string
+  //     `content_language~feed_label~offer_id`. This format is suitable only
+  //     when `content_language`, `feed_label`, and `offer_id` do not contain
+  //     URL-problematic characters like `/`, `%`, or `~`.
+  //
+  // We recommend using the **Encoded Format** for all product IDs to ensure
+  // correct parsing, especially those containing special characters. The
+  // presence of tilde (`~`) characters in the `{productinput}` segment is used
+  // to differentiate between the two formats.
+  //
+  // Note: For calls to the v1beta version, the plain format is
+  //     `channel~content_language~feed_label~offer_id`, for example:
+  //     `accounts/123/productinputs/online~en~US~sku123`.
   string name = 1 [(google.api.field_behavior) = IDENTIFIER];
 
   // Output only. The name of the processed product.
@@ -227,8 +257,8 @@ message InsertProductInputRequest {
   // Required. The primary or supplemental product data source name. If the
   // product already exists and data source provided is different, then the
   // product will be moved to a new data source. For more information, see
-  // [Overview of Data sources
-  // sub-API](/merchant/api/guides/data-sources/overview).
+  // [Create a primary data
+  // source](/merchant/api/guides/data-sources/api-sources#create-primary-data-source).
   //
   // Only API data sources are supported.
   //
@@ -243,7 +273,8 @@ message InsertProductInputRequest {
 // input must be from the same data source.
 message UpdateProductInputRequest {
   // Required. The product input resource to update. Information you submit will
-  // be applied to the processed product as well.
+  // be applied to the processed product as well. The `name` field within this
+  // resource identifies the product input to be updated.
   ProductInput product_input = 1 [(google.api.field_behavior) = REQUIRED];
 
   // Optional. The list of product attributes to be updated.
@@ -276,12 +307,44 @@ message UpdateProductInputRequest {
 
 // Request message for the DeleteProductInput method.
 message DeleteProductInputRequest {
-  // Required. The name of the product input resource to delete.
-  // Format: `accounts/{account}/productInputs/{product}`
-  // where the last section `product` consists of:
-  // `content_language~feed_label~offer_id`
-  // example for product name is
-  // `accounts/123/productInputs/en~US~sku123`.
+  // Required. The name of the product input to delete.
+  // Format: `accounts/{account}/productInputs/{productInput}`
+  //
+  // The {productInput} segment is a unique identifier for the product.
+  // This identifier must be unique within a merchant account and generally
+  // follows the structure: `content_language~feed_label~offer_id`. Example:
+  // `en~US~sku123` For legacy local products, the structure is:
+  // `local~content_language~feed_label~offer_id`. Example: `local~en~US~sku123`
+  //
+  // The format of the {productInput} segment in the URL is automatically
+  // detected by the server, supporting two options:
+  //
+  // 1.  **Encoded Format**: The `{productInput}` segment is an unpadded
+  // base64url
+  //     encoded string (RFC 4648 Section 5). The decoded string must result
+  //     in the `content_language~feed_label~offer_id` structure. This encoding
+  //     MUST be used if any part of the product identifier (like `offer_id`)
+  //     contains characters such as `/`, `%`, or `~`.
+  //     *   Example: To represent the product ID `en~US~sku/123`, the
+  //         `{productInput}` segment must be the base64url encoding of this
+  //         string, which is `ZW5-VVMtc2t1LzEyMw`. The full resource name
+  //         for the product would be
+  //         `accounts/123/productInputs/ZW5-VVMtc2t1LzEyMw`.
+  //
+  // 2.  **Plain Format**: The `{productInput}` segment is the tilde-separated
+  // string
+  //     `content_language~feed_label~offer_id`. This format is suitable only
+  //     when `content_language`, `feed_label`, and `offer_id` do not contain
+  //     URL-problematic characters like `/`, `%`, or `~`.
+  //
+  // We recommend using the **Encoded Format** for all product IDs to ensure
+  // correct parsing, especially those containing special characters. The
+  // presence of tilde (`~`) characters in the `{productInput}` segment is used
+  // to differentiate between the two formats.
+  //
+  // Note: For calls to the v1beta version, the plain format is
+  //     `channel~content_language~feed_label~offer_id`, for example:
+  //     `accounts/123/productinputs/online~en~US~sku123`.
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
diff --git a/google/shopping/merchant/products/v1/products.proto b/google/shopping/merchant/products/v1/products.proto
@@ -1,4 +1,4 @@
-// Copyright 2025 Google LLC
+// Copyright 2026 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -164,16 +164,42 @@ message Product {
 
 // Request message for the GetProduct method.
 message GetProductRequest {
-  // Required. The name of the product to retrieve.
-  // Format:
-  // `accounts/{account}/products/{product}` where the last
-  // section `product` consists of:
-  // `content_language~feed_label~offer_id`
-  // example for product name is `accounts/123/products/en~US~sku123`. A legacy
-  // local product name would be `accounts/123/products/local~en~US~sku123`.
-  // Note: For calls to the v1beta version, the `product` section consists
-  // of: `channel~content_language~feed_label~offer_id`, for example:
-  // `accounts/123/products/online~en~US~sku123`.
+  // Required. The name of the product.
+  // Format: `accounts/{account}/products/{product}`
+  //
+  // The `{product}` segment is a unique identifier for the product.
+  // This identifier must be unique within a merchant account and generally
+  // follows the structure: `content_language~feed_label~offer_id`. Example:
+  // `en~US~sku123` For legacy local products, the structure is:
+  // `local~content_language~feed_label~offer_id`. Example: `local~en~US~sku123`
+  //
+  // The format of the `{product}` segment in the URL is automatically detected
+  // by the server, supporting two options:
+  //
+  // 1.  **Encoded Format**: The `{product}` segment is an unpadded base64url
+  //     encoded string (RFC 4648 Section 5). The decoded string must result
+  //     in the `content_language~feed_label~offer_id` structure. This encoding
+  //     MUST be used if any part of the product identifier (like `offer_id`)
+  //     contains characters such as `/`, `%`, or `~`.
+  //     *   Example: To represent the product ID `en~US~sku/123`, the
+  //         `{product}` segment must be the base64url encoding of this
+  //         string, which is `ZW5-VVMtc2t1LzEyMw`. The full resource name
+  //         for the product would be
+  //         `accounts/123/products/ZW5-VVMtc2t1LzEyMw`.
+  //
+  // 2.  **Plain Format**: The `{product}` segment is the tilde-separated string
+  //     `content_language~feed_label~offer_id`. This format is suitable only
+  //     when `content_language`, `feed_label`, and `offer_id` do not contain
+  //     URL-problematic characters like `/`, `%`, or `~`.
+  //
+  // We recommend using the **Encoded Format** for all product IDs to ensure
+  // correct parsing, especially those containing special characters. The
+  // presence of tilde (`~`) characters in the `{product}` segment is used to
+  // differentiate between the two formats.
+  //
+  // Note: For calls to the v1beta version, the plain format is
+  //     `channel~content_language~feed_label~offer_id`, for example:
+  //     `accounts/123/products/online~en~US~sku123`.
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
diff --git a/google/shopping/merchant/products/v1/products_common.proto b/google/shopping/merchant/products/v1/products_common.proto
@@ -1,4 +1,4 @@
-// Copyright 2025 Google LLC
+// Copyright 2026 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -39,6 +39,9 @@ enum SubscriptionPeriod {
 
   // Indicates that the subscription period is year.
   YEAR = 2;
+
+  // Indicates that the subscription period is week.
+  WEEK = 3;
 }
 
 // Target [age group](https://support.google.com/merchants/answer/6324463) of
@@ -493,6 +496,23 @@ enum CarrierTransitTimeOption {
 
 // Product attributes.
 message ProductAttributes {
+  // The business days during which orders are on their path to fulfillment.
+  // If not provided, Monday to Friday business days will be assumed.
+  message ShippingBusinessDaysConfig {
+    // The [CLDR territory
+    // code](http://www.unicode.org/repos/cldr/tags/latest/common/main/en.xml)
+    // of the country to which an item will ship.
+    optional string country = 1;
+
+    // Effective days of the week considered for the delivery time calculation.
+    // May not be empty. The more business days included the faster the
+    // delivery. Can be set through individual days (e.g. `MTWRF`), or day
+    // ranges (e.g. `Mon-Fri`). For more information about accepted formats,
+    // see [Shipping handling business
+    // days](https://support.google.com/merchants/answer/16072859).
+    optional string business_days = 2;
+  }
+
   // Carrier-based shipping configuration. Allows for setting shipping speed or
   // shipping cost based on a carrier's provided info.
   message CarrierShipping {
@@ -912,7 +932,7 @@ message ProductAttributes {
   // Number and amount of installments to pay for an item.
   ProductInstallment installment = 32;
 
-  // Number of periods (months or years) and amount of payment per period
+  // Number of periods (weeks, months or years) and amount of payment per period
   // for an item with an associated subscription contract.
   SubscriptionCost subscription_cost = 33;
 
@@ -983,6 +1003,17 @@ message ProductAttributes {
   // Minimal product handling time (in business days).
   optional int64 min_handling_time = 45;
 
+  // The business days during which orders can be handled. If not provided,
+  // Monday to Friday business days will be assumed.
+  repeated ShippingBusinessDaysConfig shipping_handling_business_days = 143;
+
+  // The business days during which orders are in transit.
+  // If not provided, Monday to Friday business days will be assumed.
+  repeated ShippingBusinessDaysConfig shipping_transit_business_days = 144;
+
+  // The handling cutoff times for shipping.
+  repeated HandlingCutoffTime handling_cutoff_times = 141;
+
   // The shipping label of the product, used to group product in account-level
   // shipping rules.
   optional string shipping_label = 46;
@@ -1238,6 +1269,7 @@ message SubscriptionCost {
   // Supported values are:
   //   * "`month`"
   //   * "`year`"
+  //   * "`week`"
   SubscriptionPeriod period = 1;
 
   // The number of subscription periods the buyer has to pay.
@@ -1391,6 +1423,20 @@ message Shipping {
   // [maxTransitTime][google.shopping.merchant.products.v1.Shipping.max_transit_time]
   // is present.
   optional int64 max_transit_time = 11;
+
+  // The handling cutoff time until which an order has to be placed to be
+  // processed in the same day. This is a string in format of HHMM (e.g.
+  // `1530`) for 3:30 PM. If not configured, the cutoff time will be defaulted
+  // to 8AM PST and `handling_cutoff_timezone` will be ignored.
+  optional string handling_cutoff_time = 12;
+
+  // [Timezone
+  // identifier](https://developers.google.com/adwords/api/docs/appendix/codes-formats#timezone-ids)
+  // For example `Europe/Zurich`. This field only applies if
+  // `handling_cutoff_time` is set. If `handling_cutoff_time` is set but this
+  // field is not set, the shipping destination timezone will be used. If both
+  // fields are not set, the handling cutoff time will default to 8AM PST.
+  optional string handling_cutoff_timezone = 13;
 }
 
 // Conditions to be met for a product to have free shipping.
@@ -1491,6 +1537,10 @@ message ProductWeight {
 // a product computed asynchronously.
 message ProductStatus {
   // The destination status of the product status.
+  //
+  // Equivalent to
+  // [`StatusPerReportingContext`][google.shopping.merchant.reports.v1.ProductView.StatusPerReportingContext]
+  // in Reports API.
   message DestinationStatus {
     // The name of the reporting context.
     google.shopping.type.ReportingContext.ReportingContextEnum
@@ -1668,3 +1718,29 @@ message AutomatedDiscounts {
   // the product is not available.
   google.shopping.type.Price gad_price = 3;
 }
+
+// Configuration for offer or offer-country level shipping handling cutoff time.
+message HandlingCutoffTime {
+  // The [CLDR territory
+  // code](http://www.unicode.org/repos/cldr/tags/latest/common/main/en.xml)
+  // of the country to which the handling cutoff time applies.
+  optional string country = 1;
+
+  // The handling cutoff time until which an order has to be placed to be
+  // processed in the same day. This is a string in format of HHMM (e.g. `1530`)
+  // for 3:30 PM.
+  // If not configured, the cutoff time will be defaulted to 8AM PST.
+  optional string cutoff_time = 2;
+
+  // [Timezone
+  // identifier](https://developers.google.com/adwords/api/docs/appendix/codes-formats#timezone-ids)
+  // For example 'Europe/Zurich'. If not set, the shipping destination
+  // timezone will be used.
+  optional string cutoff_timezone = 3;
+
+  // This field only applies to same-day delivery. If true, prevents next-day
+  // delivery from being shown for this offer after the cutoff time. This field
+  // only applies to same-day delivery offers, for merchants who want to
+  // explicitly disable it.
+  optional bool disable_delivery_after_cutoff = 4;
+}
