feat: Added the product_id_base64_url_encoded field to InsertProductInputRequest, DeleteProductInputRequest, and GetProductRequest. This allows for product IDs containing special characters to be correctly handled when unpadded base64url-encoded

Google APIs · copybara-github · commit 20581e066dea · 2025-11-11T02:22:53.000-08:00
feat: Added `handling_cutoff_time` and `handling_cutoff_timezone` fields to the `Shipping` message within `Attributes`
feat: Added C#, PHP, and Ruby namespace options to ProductInputs, Products, and ProductsCommon proto files for improved client library generation
docs: Updated comments for several fields, including product name formats, data source creation, destination field descriptions (now also referred to as Marketing Methods), and the default page size for `ListProductsRequest`

PiperOrigin-RevId: 830818171
diff --git a/google/shopping/merchant/products/v1beta/productinputs.proto b/google/shopping/merchant/products/v1beta/productinputs.proto
@@ -25,25 +25,29 @@ import "google/protobuf/field_mask.proto";
 import "google/shopping/merchant/products/v1beta/products_common.proto";
 import "google/shopping/type/types.proto";
 
+option csharp_namespace = "Google.Shopping.Merchant.Products.V1Beta";
 option go_package = "cloud.google.com/go/shopping/merchant/products/apiv1beta/productspb;productspb";
 option java_multiple_files = true;
 option java_outer_classname = "ProductInputsProto";
 option java_package = "com.google.shopping.merchant.products.v1beta";
+option php_namespace = "Google\\Shopping\\Merchant\\Products\\V1beta";
+option ruby_package = "Google::Shopping::Merchant::Products::V1beta";
 
 // Service to use ProductInput resource.
-// This service works for products with online channel only.
 service ProductInputsService {
   option (google.api.default_host) = "merchantapi.googleapis.com";
   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
-  // must have a products 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.
+  // account](/merchant/api/guides/products/add-manage#add_a_product). You
+  // must have a products [data
+  // 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 an input with the same contentLanguage, offerId, and dataSource already
-  // exists, this method replaces that entry.
+  // If a product input with the same contentLanguage, offerId, and dataSource
+  // already exists, then the product input inserted by this method replaces
+  // that entry.
   //
   // After inserting, updating, or deleting a product input, it may take several
   // minutes before the processed product can be retrieved.
@@ -115,10 +119,14 @@ message ProductInput {
 
   // Identifier. The name of the product input.
   // Format: `accounts/{account}/productInputs/{productinput}`
-  // where the last section `productinput` consists of 4 parts:
-  // `channel~content_language~feed_label~offer_id`
+  // where the last section `productinput` consists of:
+  // `content_language~feed_label~offer_id`
   // example for product input name is
-  // `accounts/123/productInputs/online~en~US~sku123`
+  // `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`.
   string name = 1 [(google.api.field_behavior) = IDENTIFIER];
 
   // Output only. The name of the processed product.
@@ -150,8 +158,8 @@ message ProductInput {
     (google.api.field_behavior) = IMMUTABLE
   ];
 
-  // Required. Immutable. The label that lets you categorize and identify your
-  // products. The maximum allowed characters are 20, and the supported
+  // Required. Immutable. The feed label that lets you categorize and identify
+  // your products. The maximum allowed characters are 20, and the supported
   // characters are `A-Z`, `0-9`, hyphen, and underscore. The feed label must
   // not include any spaces. For more information, see [Using feed
   // labels](//support.google.com/merchants/answer/14994087).
@@ -215,8 +223,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.
   //
@@ -260,16 +268,30 @@ message UpdateProductInputRequest {
   // Format: `accounts/{account}/dataSources/{datasource}`. For example,
   // `accounts/123456/dataSources/104628`.
   string data_source = 3 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. If true, the `{productInput}` in the `name` field of the request
+  // will be interpreted as unpadded base64url-encoded and decoded during
+  // request processing to match the decoded value. Default value is `false`.
+  // Use this if your `{productInput}` contains special characters, such as
+  // forward slash
+  // `/` or other characters that are unpadded base64url-encoded (as per RFC
+  // 7515: https://datatracker.ietf.org/doc/html/rfc7515#section-2).
+  //
+  // Note that future versions of the API will only accept unpadded
+  // base64url-encoded product ids, so we strongly recommend proactively setting
+  // this to `true` and encoding the product ids.
+  bool product_id_base64_url_encoded = 4
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // 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 4 parts:
-  // `channel~content_language~feed_label~offer_id`
+  // where the last section `product` consists of:
+  // `content_language~feed_label~offer_id`
   // example for product name is
-  // `accounts/123/productInputs/online~en~US~sku123`.
+  // `accounts/123/productInputs/en~US~sku123`.
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -282,4 +304,18 @@ message DeleteProductInputRequest {
   // `accounts/{account}/dataSources/{datasource}`. For example,
   // `accounts/123456/dataSources/104628`.
   string data_source = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. If true, the `{productInput}` in the `name` field of the request
+  // will be interpreted as unpadded base64url-encoded and decoded during
+  // request processing to match the decoded value. Default value is `false`.
+  // Use this if your `{productInput}` contains special characters, such as
+  // forward slash
+  // `/` or other characters that are unpadded base64url-encoded (as per RFC
+  // 7515: https://datatracker.ietf.org/doc/html/rfc7515#section-2).
+  //
+  // Note that future versions of the API will only accept unpadded
+  // base64url-encoded product ids, so we strongly recommend proactively setting
+  // this to `true` and encoding the product ids.
+  bool product_id_base64_url_encoded = 3
+      [(google.api.field_behavior) = OPTIONAL];
 }
diff --git a/google/shopping/merchant/products/v1beta/products.proto b/google/shopping/merchant/products/v1beta/products.proto
@@ -23,10 +23,13 @@ import "google/api/resource.proto";
 import "google/shopping/merchant/products/v1beta/products_common.proto";
 import "google/shopping/type/types.proto";
 
+option csharp_namespace = "Google.Shopping.Merchant.Products.V1Beta";
 option go_package = "cloud.google.com/go/shopping/merchant/products/apiv1beta/productspb;productspb";
 option java_multiple_files = true;
 option java_outer_classname = "ProductsProto";
 option java_package = "com.google.shopping.merchant.products.v1beta";
+option php_namespace = "Google\\Shopping\\Merchant\\Products\\V1beta";
+option ruby_package = "Google::Shopping::Merchant::Products::V1beta";
 option (google.api.resource_definition) = {
   type: "merchantapi.googleapis.com/Account"
   pattern: "accounts/{account}"
@@ -84,9 +87,13 @@ message Product {
   // The name of the product.
   // Format:
   // `accounts/{account}/products/{product}` where the last
-  // section `product` consists of 4 parts:
-  // `channel~content_language~feed_label~offer_id`
-  // example for product name is `accounts/123/products/online~en~US~sku123`
+  // 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`.
   string name = 1;
 
   // Output only. The
@@ -157,17 +164,34 @@ 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 4 parts:
-  // `channel~content_language~feed_label~offer_id`
-  // example for product name is
-  // `accounts/123/products/online~en~US~sku123`
+  // 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`.
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
       type: "merchantapi.googleapis.com/Product"
     }
   ];
+
+  // Optional. If true, the `{product}` in the `name` field of the request will
+  // be interpreted as unpadded base64url-encoded and decoded during request
+  // processing to match the decoded value. Default value is `false`. Use this
+  // if your `{product}` contains special characters, such as forward slash `/`
+  // or other characters that are unpadded base64url-encoded (as per RFC 7515:
+  // https://datatracker.ietf.org/doc/html/rfc7515#section-2).
+  //
+  // Note that future versions of the API will only accept unpadded
+  // base64url-encoded product ids, so we strongly recommend proactively setting
+  // this to `true` and encoding the product ids.
+  bool product_id_base64_url_encoded = 2
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Request message for the ListProducts method.
@@ -184,7 +208,7 @@ message ListProductsRequest {
   // The maximum number of products to return. The service may return fewer than
   // this value.
   // The maximum value is 1000; values above 1000 will be coerced to 1000.
-  // If unspecified, the maximum number of products will be returned.
+  // If unspecified, the default page size of 25 products will be returned.
   int32 page_size = 2;
 
   // A page token, received from a previous `ListProducts` call.
diff --git a/google/shopping/merchant/products/v1beta/products_common.proto b/google/shopping/merchant/products/v1beta/products_common.proto
@@ -21,10 +21,13 @@ import "google/protobuf/timestamp.proto";
 import "google/shopping/type/types.proto";
 import "google/type/interval.proto";
 
+option csharp_namespace = "Google.Shopping.Merchant.Products.V1Beta";
 option go_package = "cloud.google.com/go/shopping/merchant/products/apiv1beta/productspb;productspb";
 option java_multiple_files = true;
 option java_outer_classname = "ProductsCommonProto";
 option java_package = "com.google.shopping.merchant.products.v1beta";
+option php_namespace = "Google\\Shopping\\Merchant\\Products\\V1beta";
+option ruby_package = "Google::Shopping::Merchant::Products::V1beta";
 
 // The subscription period of the product.
 enum SubscriptionPeriod {
@@ -132,7 +135,7 @@ message Attributes {
   // Deprecated: Use `gtins` instead.
   repeated string gtin = 26 [deprecated = true];
 
-  // Global Trade Item Numbers
+  // A list of Global Trade Item Numbers
   // ([GTIN](https://support.google.com/merchants/answer/188494#gtin)) of the
   // item.
   // You can provide up to 10 GTINs.
@@ -282,7 +285,7 @@ message Attributes {
   // The number of identical products in a business-defined multipack.
   optional int64 multipack = 58;
 
-  // Used to group items in an arbitrary way. Only for CPA%, discouraged
+  // Used to group items in an arbitrary way. Only for CPA, discouraged
   // otherwise. For more information, see
   // [Display ads
   // attribute](https://support.google.com/merchants/answer/6069387).
@@ -365,6 +368,9 @@ message Attributes {
   // custom grouping of items in a Shopping campaign.
   optional string custom_label_4 = 75;
 
+  // Destinations also known as [Marketing
+  // methods](https://support.google.com/merchants/answer/15130232) selections.
+  //
   // The list of destinations to include for this target (corresponds to
   // checked check boxes in Merchant Center). Default destinations are always
   // included unless provided in `excludedDestinations`.
@@ -377,6 +383,9 @@ message Attributes {
   // cases. Use this field within products to only setup exceptions.
   repeated string included_destinations = 76;
 
+  // Destinations also known as [Marketing
+  // methods](https://support.google.com/merchants/answer/15130232) selections.
+  //
   // The list of destinations to exclude for this target (corresponds to
   // unchecked check boxes in Merchant Center).
   //
@@ -433,10 +442,10 @@ message Attributes {
 
   // A safeguard in the [automated discounts]
   // (https://support.google.com/merchants/answer/10295759) and
-  // "Dynamic Promotions"
-  // (https://support.google.com/merchants/answer/13949249) projects,
-  // ensuring that discounts on business offers do not fall below this value,
-  // thereby preserving the offer's value and profitability.
+  // ["dynamic
+  // promotions"](https://support.google.com/merchants/answer/13949249)
+  // projects, ensuring that discounts on business offers do not fall below this
+  // value, thereby preserving the offer's value and profitability.
   google.shopping.type.Price auto_pricing_min_price = 124;
 
   // The list of sustainability incentive programs.
@@ -671,6 +680,20 @@ message Shipping {
   // [maxTransitTime][google.shopping.merchant.products.v1beta.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.
