@wix/bex-utils 2.1.0 → 2.2.0

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/com/wix/ecommerce/catalog_spi/api/v1/catalog_reference.proto

@@ -5,20 +5,26 @@ package com.wix.ecommerce.catalog_spi.api.v1;
 import "google/protobuf/struct.proto";
 import "wix/api/validations.proto";
 
-// Used for grouping line items and is sent on add to cart
+// Used for grouping line items. Sent when an item is added to a cart, checkout, or order.
 message CatalogReference {
-    // ID of the item within its Wix or 3rd-party catalog. For example, `productId` for Wix Stores or `bookingId` for Wix Bookings.
+
+    // ID of the item within the catalog it belongs to.
     string catalog_item_id = 1 [(.wix.api.minLength) = 1, (.wix.api.maxLength) = 36];
-    /* 
-    ID of the app providing the catalog. For items from Wix apps, the following values always apply:
+
+    /*
+    ID of the app providing the catalog.
+
+    You can get your app's ID from its page in the [Wix Dev Center](https://dev.wix.com/apps).
+
+    For items from Wix catalogs, the following values always apply:
     + Wix Stores: `"215238eb-22a5-4c36-9e7b-e7c08025e04e"`
-    + Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"`    
+    + Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"`
+    + Wix Restaurants: `"9a5d83fd-8570-482e-81ab-cfa88942ee60"`
     */
     string app_id = 2 [(.wix.api.minLength) = 1];
-    /*
-    Additional info in key:value pairs. For example, to specify Wix Stores product options or variants:
-    + `{"options": {"options": {"Size": "M", "Color": "Red"}}}`
-    + `{"options": {"variantId": "<VARIANT_ID>"}}`
-    */
+
+    // Additional item details in key:value pairs. Use this optional field to provide more specificity with item selection. The `options` field values differ depending on which catalog is providing the items.
+    //
+    // For products and variants from a Wix Stores catalog, learn more about [eCommerce integration](https://dev.wix.com/docs/rest/business-solutions/stores/catalog/e-commerce-integration).
     google.protobuf.Struct options = 3;
 }

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/com/wix/ecommerce/catalog_spi/api/v1/description_line.proto

@@ -13,11 +13,13 @@ message DescriptionLine {
         PLAIN_TEXT = 1;
         COLOR = 2;
     }
+
     // Description line name.
     DescriptionLineName name = 1;
 
 
     oneof value {
+
         // Description line plain text value.
         PlainTextValue plain_text = 5;
         // Description line color value.
@@ -29,32 +31,47 @@ message DescriptionLine {
 
     // __Deprecated.__ Use `value` instead.
     oneof descriptionLineValue {
+        
         // Description line plain text value.
         PlainTextValue plain_text_value = 3 [deprecated = true, (.wix.api.field_exposure) = PRIVATE];
+        
         // Description line color.
         string color = 4 [deprecated = true, (.wix.api.field_exposure) = PRIVATE];
     }
 }
 
 message DescriptionLineName {
-    // Description line name in site's default language.
+    
+    // Description line name in the site's default language.
     string original = 1 [(.wix.api.maxLength) = 100];
-    // Translated description line item according to buyer language. Defaults to `original` when not provided.
+    
+    // Description line name translated into the buyer's language.
+    //
+    // Default: Same as `original`.
     google.protobuf.StringValue translated = 2 [(.wix.api.maxLength) = 200];
 }
 
 message PlainTextValue {
-    // Description line plain text value in site's default language.
+    
+    // Description line plain text value in the site's default language.
     string original = 1 [(.wix.api.maxLength) = 600];
-    // Translated description line plain text value according to buyer language. Defaults to `original` when not provided.
+    
+    // Description line plain text value translated into the buyer's language.
+    //
+    // Default: Same as `original`.
     google.protobuf.StringValue translated = 2 [(.wix.api.maxLength) = 600];
 }
 
 message Color {
-    // Description line color name in site's default language.
+    
+    // Description line color name in the site's default language.
     string original = 1 [(.wix.api.maxLength) = 500];
-    // Translated description line color name according to buyer language. Defaults to `original` when not provided.
+    
+    // Description line color name translated into the buyer's language.
+    //
+    // Default: Same as `original`.
     google.protobuf.StringValue translated = 2 [(.wix.api.maxLength) = 500];
+    
     // HEX or RGB color code for display.
     google.protobuf.StringValue code = 3;
 }

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/com/wix/ecommerce/catalog_spi/api/v1/item_data.proto

@@ -19,72 +19,98 @@ import "com/wix/ecommerce/catalog_spi/api/v1/price_description.proto";
 import "wix/coupons/api/v2/scope.proto";
 
 message ItemData {
+
     /*
-    **Required** - Item name.
-    + Stores - `product.name`
-    + Bookings - `service.info.name`
-    + Events - `ticket.name`
+    __Required.__ Item name.
     */
     ProductName product_name = 1;
-    // Optional - URL to the item's page on the site. When not provided, the link back from the cart page to the relevant product page will not work.
-    // The URL is optional and if not provided, the site URL will be used.
+
+    // URL for the item's page on the site. 
+    //
+    // This is used to link back to the relevant item page from the cart page. If not provided, the site URL is used.
     .wix.common.PageUrlV2 url = 2;
-    // **Required** - Item type. Either a preset type or custom.
+
+    // __Required.__ Item type. Either one of the preset types or a custom type.
     ItemType item_type = 11;
-    // **Required** - Item price **after** catalog-defined discount.
+
+    // __Required.__ Item price with discounts applied. If a catalog-defined discount applies, the discount is reflected in this price.
     string price = 3 [(.wix.api.decimalValue) = { gte: "0" lte: "1000000000000000"}];
-    // Optional - Item price **before** catalog-defined discount. Defaults to `price` when not provided.
+
+    // Item price **before** applying any catalog-defined discount.
+    //
+    // Default: Value of `price` field, if no catalog-defined discount applies.
     google.protobuf.StringValue full_price = 5 [(.wix.api.format) = DECIMAL_VALUE];
-    // Optional - Tax group for the product. Currently an internal field for Stores only.
+
+    // The tax group ID associated with this item.
     google.protobuf.StringValue tax_group_id = 4 [(.wix.api.format) = GUID];
-    // Optional - Line item description lines. Line item description lines. Used for displaying the cart, checkout and order.
-    // For example, if you want `Size: Large` to appear under the item name, create a description line with `{"name": {"original": "Size"}}` and  `{"plainText": {"original": "Large"}}`.
+
+    // Line item description lines. Used for displaying the item in a cart, checkout or order. For example, if you want `Size: Large` to appear under the item name, create a description line with `"name": {"original": "Size"}` and  `"plainText": {"original": "Large"}`.
+    //
+    // Default: No description line.
     repeated DescriptionLine description_lines = 6 [(.wix.api.minSize) = 0, (.wix.api.maxSize) = 20];
-    /*
-    Optional - Line item image.
-    + Pass at least media ID, width, and height. You should be able to get these values when you upload an image to Wix media manager.
-    + Given a full image URL of https://static.wixstatic.com/media/5cc69183e7954e2c9760fa2383870992.jpg, `media.id` would be "5cc69183e7954e2c9760fa2383870992.jpg".
-    + We only support images coming from Wix media manager, if you want to use an image from another source you must first upload it to Wix media manager.
-    + We are working on removing `altText` as it is not being used by our systems.
-    */
+
+    // Line item image details. Supports images from the [Wix Media Manager](https://support.wix.com/en/article/wix-media-accessing-the-media-manager) only. 
+    //
+    // To use an image from another source, first upload it to the Media Manager. 
+    // You can retrieve the ID, width and height of an image from the Wix Media Manager.
     Image media = 7;
-    // Optional - Item quantity available for purchase. Only return this if inventory is managed.
-    // Not returning this field means that the buyer can "infinitely" tick up the number of items in the cart.
-    google.protobuf.Int32Value quantity_available = 8 [(.wix.api.min) = 0, (.wix.api.max) = 100000];
-    // Optional - Physical properties of the item. When relevant, contains information such as SKU and item weight.
+
+    // Quantity of the item available for purchase. Only return if the catalog manages inventory. 
+    // If not returned, a buyer can increase the quantity of this item to add to the cart or checkout without limit.
+    google.protobuf.Int32Value quantity_available = 8 [(.wix.api.min) = 0, (.wix.api.max) = 100000000];
+
+    // Physical properties of the item. Only return for physical items. When applicable, contains information such as SKU and item weight.
     PhysicalProperties physical_properties = 9;
-    // Optional - Coupon scopes - which app and items a coupon applies to.
-    // This field is internal to Wix, and should be used by Bookings, Stores and Events as used by the current [Coupons API](https://bo.wix.com/wix-docs/rest/stores/coupons/valid-scope-values).
+
+    // Coupon scopes. These specify which app and items a coupon applies to.
+    // Should be used by Bookings, Stores, and Events in line with the current [Coupons API](https://bo.wix.com/wix-docs/rest/stores/coupons/valid-scope-values).
     repeated .wix.coupons.api.v2.Scope coupon_scopes = 10 [(.wix.api.field_exposure) = INTERNAL];
-    // Optional - Subscription option info. This field is internal and only used by Stores.
+
+    // Subscription option info. This field is internal and only used by Stores.
     SubscriptionOptionInfo subscription_option_info = 12 [(.wix.api.field_exposure) = PRIVATE];
+
     // ID of the fulfiller for this item. This field is internal and only used by Stores.
     google.protobuf.StringValue fulfiller_id = 13 [(.wix.api.referenced_entity) = "wix.ecom.v1.fulfiller", (.wix.api.field_exposure) = INTERNAL, (.wix.api.format) = GUID];
-    // Digital file ID and name. Required if `itemType: DIGITAL`.
+
+    // Digital file details. Required if `itemType.preset` is `DIGITAL`.
     SecuredMedia digital_file = 14 [(.wix.api.field_exposure) = INTERNAL];
-    // Optional - Shipping group ID. This field is internal and only used by Stores.
+
+    // Shipping group ID. This field is internal and only used by Stores.
     google.protobuf.StringValue shipping_group_id = 15 [(.wix.api.field_exposure) = PRIVATE, (.wix.api.format) = GUID, (.wix.api.readOnly) = true];
-    // Optional - Type of selected payment option for current item. Defaults to `FULL_PAYMENT_ONLINE`.
-    // + `FULL_PAYMENT_ONLINE` - Entire payment for this item happens as part of the checkout.
-    // + `FULL_PAYMENT_OFFLINE` - Entire payment for this item happens after the checkout. For example, when using cash, check, or other offline payment methods.
-    // + `MEMBERSHIP` - Payment for this item is done by charging a membership. When this option is used, `lineItem.price.amount` is 0.
-    // + `DEPOSIT_ONLINE` -  Partial payment for the given item to be paid upfront during the checkout. Amount to be paid is defined by deposit_amount field.
+
+    // Payment method selected for the item.
+    // 
+    // + `FULL_PAYMENT_ONLINE`: The entire payment for this item happens as part of the checkout.
+    // + `FULL_PAYMENT_OFFLINE`: The entire payment for this item happens after the checkout. For example, when using cash, check, or other offline payment methods. 
+    // + `MEMBERSHIP`: Payment for this item is done by charging a membership. When selected, `price` is `0`.
+    // + `DEPOSIT_ONLINE`: Partial payment to be paid upfront during the checkout. Initial amount to be paid for each line item is specified in `depositAmount`.
+    // + `MEMBERSHIP_OFFLINE`: Payment for this item can only be done by charging a membership and must be manually redeemed in the dashboard by the site admin. When selected, `price` is `0`.
+    //
+    // Default: `FULL_PAYMENT_ONLINE`.
     PaymentOptionType payment_option = 17;
-    // Optional - Service properties. When relevant, this contains information such as date and number of participants.
-    // Used, among other things, when checking for valid memberships.
+
+    // Service properties. When applicable, this contains information such as time and number of participants.
     ServiceProperties service_properties = 18;
-    // Optional - In cases where `catalogReference.catalogItemId` is NOT the actual catalog item ID, this field will return the true item's ID.
-    // + For example, for Wix Bookings, `catalogReference.catalogItemId` is the booking ID. Therefore this value is set to the service ID.
-    // + in most cases, this field is the name as `catalogReference.catalogItemId`.
-    // + Used in membership validation.
+
+    // Additional ID for the item in the catalog.
+    // This field provides an additional identifier for the item if your flow requires another ID as well as `catalogReference.catalogItemId`.
+    // Can be used for membership validation.
+    //
+    // Default: Same as `catalogReference.catalogItemId`.
     google.protobuf.StringValue root_catalog_item_id = 19 [(.wix.api.minLength) = 1, (.wix.api.maxLength) = 36];
-    // Optional - Additional description for the price. For example, when passing `"price": "0"` but additional details about the actual price are needed - "Starts at $67".
+
+    // Additional description for the price. Return when additional information about the price is needed.
+    //
+    // For example, when `price` is `"0"` but additional details about the actual price are needed, such as `"Starts at $67"`.
     PriceDescription price_description = 20;
-    // Optional - partial payment for the given item to be paid upfront during the checkout.
-    // Eligible for catalog items with type `DEPOSIT_ONLINE`.
-    // If omitted - item's price will not be split and is expected to be paid in single installment
+
+    
+    // Partial payment to be paid upfront during the checkout. Return when `paymentOption` is `DEPOSIT_ONLINE`.
+    //
+    // Default: If `paymentOption` is `DEPOSIT_ONLINE` but `depositAmount` is not provided, the item is treated as if `paymentOption` is `FULL_PAYMENT_ONLINE`.
     google.protobuf.StringValue deposit_amount = 21 [(.wix.api.format) = DECIMAL_VALUE];
-    // Delivery Profile Id for the product
+
+    // Delivery profile ID for the product.
     google.protobuf.StringValue delivery_profile_id = 22 [(.wix.api.format) = GUID, (.wix.api.field_exposure) = INTERNAL];
 
 }

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/com/wix/ecommerce/catalog_spi/api/v1/item_media.proto

@@ -16,16 +16,25 @@ message Image {
         field: "height"
         field: "width"
     };
-    // WixMedia image ID.
+
+    // __Required.__ WixMedia image ID.
+    //
+    // Given a full image URL of `https://static.wixstatic.com/media/5cc69183e7954e2c9760fa2383870992.jpg`, `media.id` is `5cc69183e7954e2c9760fa2383870992.jpg`.
     string id = 1;
+    
     reserved 2;
-    // Original image height.
+    
+    // __Required.__ Image height.
     int32 height = 3 [(.wix.api.readOnly) = true];
-    // Original image width.
+    
+    // __Required.__ Image width.
     int32 width = 4 [(.wix.api.readOnly) = true];
-    // Image alt text. Optional.
+    
+    // Image alt text.
     google.protobuf.StringValue alt_text = 5;
+    
     reserved 6;
-    // Image filename. Optional.
+    
+    // Image filename.
     google.protobuf.StringValue filename = 7 [(.wix.api.readOnly) = true];
 }

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/com/wix/ecommerce/catalog_spi/api/v1/item_type.proto

@@ -4,9 +4,11 @@ package com.wix.ecommerce.catalog_spi.api.v1;
 
 message ItemType  {
     oneof itemTypeData {
+
         // Preset item type.
         ItemType preset = 1;
-        // Custom item type.
+        
+        // Custom item type. When none of the preset types are suitable, specifies the custom type.
         string custom = 2;
     }
 

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/com/wix/ecommerce/catalog_spi/api/v1/payment_option.proto

@@ -4,16 +4,19 @@ package com.wix.ecommerce.catalog_spi.api.v1;
 
 // Type of selected payment option for catalog item
 enum PaymentOptionType {
-  // The entire payment for given item will happen as part of the checkout.
+  
+  // The entire payment for this item happens as part of the checkout.
   FULL_PAYMENT_ONLINE = 0;
-  // The entire payment for given item will happen after the checkout.
+  
+  // The entire payment for this item happens after the checkout. For example, when using cash, check, or other offline payment methods. 
   FULL_PAYMENT_OFFLINE = 1;
-  // Given item cannot be paid via monetary payment options, only via membership. When this option is used, price will always be 0.
+
+  // Payment for this item is done by charging a membership. When selected, `price` is `0`.
   MEMBERSHIP = 2;
-  // Partial payment for the given item to be paid upfront during the checkout.
-  // Amount to be paid is defined by `deposit_amount` field on per-item basis.
+
+  // Partial payment to be paid upfront during the checkout. Initial amount to be paid for each line item is specified in `depositAmount`.
   DEPOSIT_ONLINE = 3;
-  // Payment for this item can only be done using a membership and must be manually redeemed in the dashboard by the site owner.
-  // Note: when this option is used, price will be 0.
+
+  // Payment for this item can only be done by charging a membership and must be manually redeemed in the dashboard by the site admin. When selected, `price` is `0`.
   MEMBERSHIP_OFFLINE = 4;
 }

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/com/wix/ecommerce/catalog_spi/api/v1/physical_properties.proto

@@ -6,10 +6,13 @@ import "google/protobuf/wrappers.proto";
 import "wix/api/validations.proto";
 
 message PhysicalProperties {
-    // Line item weight. Measurement unit (KG or LB) is taken from `order.weightUnit`.
+
+    // Line item weight. Measurement unit matches the weight unit specified in `weightUnit` in the request.
     google.protobuf.DoubleValue weight = 1;
+    
     // Stock-keeping unit. Learn more about [SKUs](https://www.wix.com/encyclopedia/definition/stock-keeping-unit-sku).
     google.protobuf.StringValue sku = 2 [(.wix.api.maxLength) = 40];
+    
     // Whether this line item is shippable.
     bool shippable = 3;
 }

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/com/wix/ecommerce/catalog_spi/api/v1/platform_catalog_spi.proto

@@ -16,18 +16,44 @@ import "com/wix/ecommerce/catalog_spi/api/v1/item_media.proto";
 
 
 service PlatformCatalogSPI {
-    option (.wix.api.service_entity).message = "com.wix.ecommerce.catalog_spi.api.v1.CatalogProvider";
     option (.wix.spi.service) = {
+        fqdn: "wix.interfaces.ecommerce.v1.catalog_provider"
         spi_identifier: "com.wixpress.appservice.api.ComponentType.ECOM_CATALOG"
         config_message: "com.wix.ecommerce.catalog_spi.api.v1.CatalogSPIConfig"
         host_service: "com.wix.ecom.catalog_spi_host.CatalogSpiHostService"
         app_id: "1380b703-ce81-ff05-f115-39571d94dfcd" // SPI Host's App Id
     };
-
-    // Retrieves specified item data from a specified catalog.
+    option (.wix.api.service_exposure) = PUBLIC;
+    option (.wix.api.service_maturity) = BETA;
+
+    // Retrieves data for specified items in a specified catalog.
+    //
+    // Wix calls this endpoint whenever a cart or checkout is updated, and when an item is added to an order.
+    // 
+    // The endpoint receives a `catalogReferences` array. Each catalog reference in the array contains: 
+    // + The ID of the item whose latest information Wix needs to retrieve.
+    // + The ID of the app providing the catalog containing the item.
+    // + Optional details about preferences or customization of the item.
+    //
+    // The endpoint also receives preferences for the currency and weight unit to be used in the response.
+    //
+    // Your external catalog can store and organize item details in any way you prefer.
+    // When implementing the Catalog SPI, learn how to [handle item variants](../../../../docs/Catalog-Reference.md) in a way that meets your needs.
+    //
+    // The endpoint's response must contain a `catalogItems` array. Each item in the array must contain:
+    // + A `catalogReference` object. This must be identical to the `catalogReference` object received in the request.
+    // + A `data` object with full details about the item.
+    //
+    // > **Notes:**
+    // > + If an item doesn't exist in the catalog, the response must exclude it from the `catalogItems` array in the response. 
+    // > + When none of the items requested exist in the catalog, `catalogItems` must contain an empty array.
+    // > + Wix calls the endpoint every time a cart or checkout is updated. If the response doesn't include an item that was already in the cart or checkout, Wix removes the item from the cart or checkout.
     rpc GetCatalogItems (GetCatalogItemsRequest) returns (GetCatalogItemsResponse) {
         option (google.api.http) = {
             post: "get-catalog-items"
+            additional_bindings {
+                post: "/v1/get-catalog-items"
+            }
         };
     }
 
@@ -38,65 +64,113 @@ service PlatformCatalogSPI {
     }
 }
 
-message CatalogProvider {
-    option (.wix.api.entity) = {
-        fqdn: "wix.interfaces.ecommerce.v1.catalog_provider"
-        segment: PUBLIC
-    };
-}
-
 message CatalogSPIConfig {
-    // The URL of the SPI implementation
+
+    // Base URI which Wix eCommerce will call to access Catalog SPI endpoints. For example, to call the Get Catalog Items endpoint at `https://my-external-catalog.com/get-catalog-items`, the base URI you provide here is `https://my-external-catalog.com`.
     string deployment_uri = 1 [(.wix.spi.base_uri) = true];
-    //The enablement and UI configuration for discount of all items in the catalog
-    DiscountConfig all_items_discount = 2;
-    //The enablement and UI configuration for discount of specific items in the catalog
-    DiscountConfig specific_items_discount = 3;
-    // The translation key for catalog business name, visible to Users when choosing catalogs.
-    // For example: "Wix Stores - Items", "Bookings services"
-    // Wix applications implementing this SPI should make sure to add translations to this key the scopes SPI host
-    string name_translation_key = 4 [(.wix.api.minLength) = 1, (.wix.api.maxLength) = 100];
+    
+    // Configuration details for discounts applied to all items in the catalog. 
+    AllItemsDiscountConfig all_items_discount = 2;
+    
+    // Configuration details for discounts applied to specific items in the catalog.
+    SpecificItemsDiscountConfig specific_items_discount = 3;
+    
+    reserved 4;
+}
+
+// Configuration for all items discount functionality in the catalog.
+message AllItemsDiscountConfig {
+    
+    // Whether the discount is enabled. 
+    //
+    // Default: `false`.
+    bool enabled = 1;
+    
+    // Translation key for text to display to the site owner.
+    // __Deprecated.__ Use `name` instead.
+    string translation_key = 2 [(.wix.api.minLength) = 5, (.wix.api.maxLength) = 30, (.wix.api.field_exposure) = INTERNAL, (.wix.api.field_deprecated) = {
+        replaced_by: "name"
+        target_removal_date: "2024-05-01"
+    }];
+
+    // Translatable name for "all items discount" in the catalog.
+    // For example, for restaurant menus, this could be "All dishes".
+    google.protobuf.StringValue name = 5 [(.wix.api.minLength) = 1, (.wix.api.maxLength) = 100, (.wix.api.translatable)= {
+        type: LONG_TEXT
+        name: "All items discount name"
+        grouping: "Catalog configuration fields"
+    }];
 }
 
-// Configuration for discount functionality on the catalog
-message DiscountConfig {
-    //Signifies if the discount is  enabled  in the service
+// Configuration for discount functionality in the catalog.
+message SpecificItemsDiscountConfig {
+
+    // Whether the discount is enabled.
+    //
+    // Default: `false`.
     bool enabled = 1;
-    //The translation key to get the text to display to the user
-    string translation_key = 2 [(.wix.api.minLength) = 5, (.wix.api.maxLength) = 30];
+
+    // Translation key for text to display to the site owner. deprecated use name instead .
+    // For example, for restaurant menus, this could be "Specific dishes".
+    string translation_key = 2 [(.wix.api.minLength) = 5, (.wix.api.maxLength) = 30, (.wix.api.field_exposure) = INTERNAL, (.wix.api.field_deprecated) = {
+        replaced_by: "name"
+        target_removal_date: "2024-05-01"
+    }];
+
+
+    // Translatable name for "all items discount" in the catalog.
+    google.protobuf.StringValue name = 5 [(.wix.api.minLength) = 1, (.wix.api.maxLength) = 100, (.wix.api.translatable)= {
+        type: LONG_TEXT
+        name: "Specific items discount name"
+        grouping: "Catalog configuration fields"
+    }];
 }
 
 message GetCatalogItemsRequest {
-    // Catalog and items references and quantities.
+    
+    // Catalog reference details for the items to retrieve, including quantity of each item.
     repeated CatalogReferenceAndQuantity catalog_references = 1 [(.wix.api.minSize) = 1, (.wix.api.maxSize) = 300];
-    // Weight measurement unit. Defaults to site weight unit.
+    
+    // Weight measurement unit. 
+    //
+    // By default, Wix sends the weight unit specified in the site's settings.
     com.wix.ecommerce.platform_common.api.WeightUnit weight_unit = 2;
-    // Currency code the items' prices will be presented in. For example, `"USD"` or `"EUR"`. Defaults to site currency.
+    
+    // Currency to return item prices in, in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, `USD` or `EUR`.
+    //
+    // By default, Wix sends the currency specified in the site's settings.
     string currency = 3 [(.wix.api.format) = CURRENCY];
-    // Instance ID. Set only when calling HTTP providers.
-    google.protobuf.StringValue instance_id = 4;
+
+    reserved 4;
 }
 
 message GetCatalogItemsResponse {
-    // Catalog info and item data.
+    
+    // Details for each item, including catalog reference details and item data. Any items that don't exist in the catalog are excluded.
+    // If none of the requested items exist in the catalog, this array must be empty.
     repeated Item catalog_items = 1;
 }
 
 message CatalogReferenceAndQuantity {
-    // Catalog and item reference info.
+   
+    // Catalog and item reference info. Holds IDs for the item and the catalog it belongs to, as well as further optional details. This is identical in the request and response.
     CatalogReference catalog_reference = 1;
+   
     // Item quantity.
     int32 quantity = 2;
 }
 
 message Item {
-    // Catalog and item reference info.
+   
+    // Catalog and item reference info. Holds IDs for the item and the catalog it belongs to, as well as further optional details. This is identical in the request and response.
     CatalogReference catalog_reference = 1;
-    // Item data.
+   
+    // Item data. Contains full details about the item.
     ItemData data = 2;
 }
 
 message QueryCatalogItemsRequest {
+  
     // A list of itemIDs to filter by. If exists, the result will only include the items with the IDs passed.
     repeated google.protobuf.StringValue catalog_item_ids = 1 [(.wix.api.minLength) = 1, (.wix.api.maxLength) = 100, (.wix.api.maxSize) = 100];
 
@@ -147,8 +221,10 @@ message BasicItem {
 
 
 message NumericPropertyRange {
+
     // Minimum value.
     double min_value = 1;
+    
     // Maximum value.
     double max_value = 2;
 }

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/com/wix/ecommerce/catalog_spi/api/v1/price_description.proto

@@ -6,8 +6,12 @@ import "google/protobuf/wrappers.proto";
 import "wix/api/validations.proto";
 
 message PriceDescription {
-    // **Required.** Original price description in site's default language.
+
+    // __Required.__ Price description in the site's default language.
     string original = 1 [(.wix.api.minLength) = 1, (.wix.api.maxLength) = 100];
-    // Translated price description according to buyer language. Defaults to `original` when not provided.
+    
+    // Price description translated into the buyer's language.
+    //
+    // Default: Same as `original`.
     google.protobuf.StringValue translated = 2 [(.wix.api.minLength) = 1, (.wix.api.maxLength) = 100];
 }

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/com/wix/ecommerce/catalog_spi/api/v1/product_name.proto

@@ -6,16 +6,21 @@ import "google/protobuf/wrappers.proto";
 import "wix/api/validations.proto";
 
 message ProductName {
+
     /* 
-    __Required.__ Original item name in site's default language.  
-    Min: 1 character  
-    Max: 200 characters
+    __Required.__ Item name in the site's default language.
+
+    Min: 1 character.  
+    Max: 200 characters.
     */
     string original = 1 [(.wix.api.minLength) = 1, (.wix.api.maxLength) = 200];
+    
     /*
-    Optional. Translated item name according to buyer language. Defaults to `original` when not provided.  
-    Min: 1 character  
-    Max: 400 characters
+    Item name translated into the buyer's language.
+
+    Min: 1 character.  
+    Max: 400 characters.
+    Default: Same as `original`.
     */
     google.protobuf.StringValue translated = 2 [(.wix.api.minLength) = 1, (.wix.api.maxLength) = 400];
 }

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/com/wix/ecommerce/catalog_spi/api/v1/secured_media.proto

@@ -5,10 +5,13 @@ package com.wix.ecommerce.catalog_spi.api.v1;
 import "wix/api/validations.proto";
 
 message SecuredMedia {
-    // Media ID in media manager.
+
+    // Media ID in Wix Media Manager.
     string id = 1 [(.wix.api.minLength) = 1, (.wix.api.maxLength) = 100];
-    // Original file name.
+    
+    // Original filename.
     string file_name = 2 [(.wix.api.minLength) = 1, (.wix.api.maxLength) = 1000];
+    
     // File type.
     FileType file_type = 3;
 

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/com/wix/ecommerce/catalog_spi/api/v1/service_properties.proto

@@ -7,8 +7,11 @@ import "google/protobuf/wrappers.proto";
 import "wix/api/validations.proto";
 
 message ServiceProperties {
-    // Date and time the service is supposed to be provided in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. For example, the time of the class.
+
+    // Date and time the service is to be provided, in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format.
+    // For example, the start time of a class.
     google.protobuf.Timestamp scheduled_date = 1;
-    // The number of people participating in this service. For example, the number of people attending the class or the number of people per hotel room.
+
+    // The number of people participating in the service. For example, the number of people attending a class or the number of people per hotel room.
     google.protobuf.Int32Value number_of_participants = 2 [(.wix.api.min) = 1, (.wix.api.max) = 10000];
 }