From 6db5d2e6bc3a762fccebbcbcfb8681a6ebaf008e Mon Sep 17 00:00:00 2001 From: Google APIs Date: Fri, 10 Apr 2026 02:32:01 -0700 Subject: [PATCH] docs: A comment for field `name` in message `.google.shopping.merchant.products.v1.LocalInventory` is changed docs: A comment for field `name` in message `.google.shopping.merchant.products.v1.RegionalInventory` is changed feat: a new field `base64_encoded_name` is added to the `LocalInventory` message feat: new field `base64_encoded_name` is added to the `RegionalInventory` message PiperOrigin-RevId: 897575741 --- .../inventories/v1/inventories_common.proto | 78 +++++++++- .../inventories/v1/localinventory.proto | 136 ++++++++++++++++- .../inventories/v1/regionalinventory.proto | 143 +++++++++++++++++- 3 files changed, 353 insertions(+), 4 deletions(-) diff --git a/google/shopping/merchant/inventories/v1/inventories_common.proto b/google/shopping/merchant/inventories/v1/inventories_common.proto index eab57d2e02..30f0ada91f 100644 --- a/google/shopping/merchant/inventories/v1/inventories_common.proto +++ b/google/shopping/merchant/inventories/v1/inventories_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. @@ -145,6 +145,60 @@ message LocalInventoryAttributes { // bytes. optional string instore_product_location = 8 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. An optional list of loyalty programs containing applicable + // loyalty member prices for this product at this store. + // + // This field is used to show store-specific member prices on Local + // Inventory Ads (LIA). + // + // To use this, the loyalty program must be configured in Google Merchant + // Center. The benefits provided must match the merchant's website and be + // clear to members. This is only applicable for merchants in supported + // countries. + // + // See [Loyalty program](https://support.google.com/merchants/answer/12922446) + // for details on supported countries and loyalty program configuration. + // For local inventory specific details, see the [Local inventory data + // specification](https://support.google.com/merchants/answer/3061342). + repeated InventoryLoyaltyProgram loyalty_programs = 10 + [(google.api.field_behavior) = OPTIONAL]; +} + +// A message that represents loyalty program. +message InventoryLoyaltyProgram { + // The label of the loyalty program. This is an internal label that uniquely + // identifies the relationship between a business entity and a loyalty + // program entity. The label must be provided if there are multiple loyalty + // programs available for the merchant, so that the system can associate + // the assets below (for example, price and points) with the correct business. + // The corresponding program must be linked to the Merchant Center account. + optional string program_label = 1; + + // The label of the tier within the loyalty program. + // Must match one of the labels within the program. + optional string tier_label = 2; + + // The price for members of the given tier, that is, the instant discount + // price. Must be smaller or equal to the regular price. + optional google.shopping.type.Price price = 3; + + // The cashback that can be used for future purchases. + optional google.shopping.type.Price cashback_for_future_use = 4; + + // The amount of loyalty points earned on a purchase. + optional int64 loyalty_points = 5; + + // A date range during which the item is eligible for member price. If not + // specified, the member price is always applicable. The date range is + // represented by a pair of ISO 8601 dates separated by a space, + // comma, or slash. + optional google.type.Interval member_price_effective_interval = 6; + + // The label of the shipping benefit. If the field has value, this offer has + // loyalty shipping benefit. If the field value isn't provided, the item is + // not eligible for loyalty shipping for the given loyalty tier. + optional string shipping_label = 7; } // Regional inventory attributes. @@ -181,4 +235,26 @@ message RegionalInventoryAttributes { // product in this region. optional Availability availability = 4 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. An optional list of loyalty programs containing applicable + // loyalty member prices for this product in this region. + // + // This field is used to show region-specific member prices on Product + // Listing Ads (PLA). + // + // To use this, the loyalty program must be configured in Google Merchant + // Center, and the merchant must be using the Regional Availability and + // Pricing (RAAP) feature. The benefits provided must match the merchant's + // website and be clear to members. This is only applicable for merchants in + // supported countries. + // + // See [Loyalty program](https://support.google.com/merchants/answer/12922446) + // for details on supported countries and loyalty program configuration. + // Also see [Regional availability and + // pricing](https://support.google.com/merchants/answer/14644124) and [How to + // set up regional member + // pricing](https://support.google.com/merchants/answer/16388178) for more + // information. + repeated InventoryLoyaltyProgram loyalty_programs = 5 + [(google.api.field_behavior) = OPTIONAL]; } diff --git a/google/shopping/merchant/inventories/v1/localinventory.proto b/google/shopping/merchant/inventories/v1/localinventory.proto index 5816a6f4be..e4bb194056 100644 --- a/google/shopping/merchant/inventories/v1/localinventory.proto +++ b/google/shopping/merchant/inventories/v1/localinventory.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. @@ -99,8 +99,51 @@ message LocalInventory { // Output only. The name of the `LocalInventory` resource. // Format: // `accounts/{account}/products/{product}/localInventories/{store_code}` + // + // 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` for + // `store_code` "store123", the `{product}` segment must be the + // base64url encoding of this string, which is `ZW5-VVN-c2t1LzEyMw`. + // The full resource name for the local inventory would be + // `accounts/123/products/ZW5-VVN-c2t1LzEyMw/localInventories/store123`. + // + // 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. string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; + // Output only. The unpadded base64url encoded name of the `LocalInventory` + // resource. Format: + // `accounts/{account}/products/{product}/localInventories/{store_code}` + // where the `{product}` segment is the unpadded base64url encoded value of + // the identifier of the form `content_language~feed_label~offer_id`. Example: + // `accounts/123/products/ZW5-VVN-c2t1LzEyMw/localInventories/store123` for + // the decoded product ID `en~US~sku/123` and `store_code` "store123". + // Can be used directly as input to the API methods that require the local + // product identifier within the local inventory name to be encoded if it + // contains special characters, for example + // [`GetLocalInventory`](https://developers.google.com/merchant/api/reference/rest/inventories_v1/accounts.products.localInventories/get). + string base64_encoded_name = 15 [(google.api.field_behavior) = OUTPUT_ONLY]; + // Output only. The account that owns the product. This field will be ignored // if set by the client. int64 account = 2 [(google.api.field_behavior) = OUTPUT_ONLY]; @@ -125,6 +168,36 @@ message ListLocalInventoriesRequest { // Required. The `name` of the parent product to list local inventories for. // 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 unpadded base64url encoding of this + // string, which is `ZW5-VVN-c2t1LzEyMw`. The full resource name + // for the product would be + // `accounts/123/products/ZW5-VVN-c2t1LzEyMw`. + // + // 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. string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -164,6 +237,36 @@ message ListLocalInventoriesResponse { message InsertLocalInventoryRequest { // Required. The account and product where this inventory will be inserted. // 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 unpadded base64url encoding of this + // string, which is `ZW5-VVN-c2t1LzEyMw`. The full resource name + // for the product would be + // `accounts/123/products/ZW5-VVN-c2t1LzEyMw`. + // + // 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. string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -182,6 +285,37 @@ message DeleteLocalInventoryRequest { // Required. The name of the local inventory for the given product to delete. // Format: // `accounts/{account}/products/{product}/localInventories/{store_code}` + // + // 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` for + // `store_code` "store123", the `{product}` segment must be the + // unpadded base64url encoding of this string, which is + // `ZW5-VVN-c2t1LzEyMw`. The full resource name for the local + // inventory would be + // `accounts/123/products/ZW5-VVN-c2t1LzEyMw/localInventories/store123`. + // + // 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. string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { diff --git a/google/shopping/merchant/inventories/v1/regionalinventory.proto b/google/shopping/merchant/inventories/v1/regionalinventory.proto index 67805030a9..5a894df83e 100644 --- a/google/shopping/merchant/inventories/v1/regionalinventory.proto +++ b/google/shopping/merchant/inventories/v1/regionalinventory.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. @@ -96,9 +96,54 @@ message RegionalInventory { // Output only. The name of the `RegionalInventory` resource. // Format: - // `{regional_inventory.name=accounts/{account}/products/{product}/regionalInventories/{region}` + // `accounts/{account}/products/{product}/regionalInventories/{region}` + // + // 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` for + // `region` "region123", the `{product}` segment must be the + // unpadded base64url encoding of this string, which is + // `ZW5-VVN-c2t1LzEyMw`. The full resource name for the regional + // inventory would be + // `accounts/123/products/ZW5-VVN-c2t1LzEyMw/regionalInventories/region123`. + // + // 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. string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; + // Output only. The unpadded base64url encoded name of the `RegionalInventory` + // resource. Format: + // `accounts/{account}/products/{product}/regionalInventories/{region}` + // where the `{product}` segment is the unpadded base64url encoded value of + // the identifier of the form `content_language~feed_label~offer_id`. Example: + // `accounts/123/products/ZW5-VVN-c2t1LzEyMw/regionalInventories/region123` + // for the decoded product ID `en~US~sku/123` and `region` "region123". + // Can be used directly as input to the API methods that require the product + // identifier within the regional inventory name to be encoded if it contains + // special characters, for example + // [`GetRegionalInventory`](https://developers.google.com/merchant/api/reference/rest/inventories_v1/accounts.products.regionalInventories/get). + string base64_encoded_name = 10 [(google.api.field_behavior) = OUTPUT_ONLY]; + // Output only. The account that owns the product. This field will be ignored // if set by the client. int64 account = 2 [(google.api.field_behavior) = OUTPUT_ONLY]; @@ -121,6 +166,37 @@ message RegionalInventory { message ListRegionalInventoriesRequest { // Required. The `name` of the parent product to list `RegionalInventory` // resources for. 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 unpadded base64url encoding of this + // string, which is `ZW5-VVN-c2t1LzEyMw`. The full resource name + // for the product would be + // `accounts/123/products/ZW5-VVN-c2t1LzEyMw`. + // + // 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. string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -160,6 +236,37 @@ message ListRegionalInventoriesResponse { message InsertRegionalInventoryRequest { // Required. The account and product where this inventory will be inserted. // 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 unpadded base64url encoding of this + // string, which is `ZW5-VVN-c2t1LzEyMw`. The full resource name + // for the product would be + // `accounts/123/products/ZW5-VVN-c2t1LzEyMw`. + // + // 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. string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -179,6 +286,38 @@ message DeleteRegionalInventoryRequest { // Required. The name of the `RegionalInventory` resource to delete. // Format: // `accounts/{account}/products/{product}/regionalInventories/{region}` + // + // 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` for + // `region` "region123", the `{product}` segment must be the + // unpadded base64url encoding of this string, which is + // `ZW5-VVN-c2t1LzEyMw`. The full resource name for the regional + // inventory would be + // `accounts/123/products/ZW5-VVN-c2t1LzEyMw/regionalInventories/region123`. + // + // 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. string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = {