0
# Product Management
1

2
Comprehensive product catalog operations including creating, updating, and managing product information, inventory, and fulfillment details. The Product Service provides both synchronous and asynchronous clients for optimal performance in different application contexts.
3

4
## Capabilities
5

6
### Basic Product Operations
7

8
Core CRUD operations for managing products in your retail catalog.
9

10
```python { .api }
11
class ProductServiceClient:
12
    def create_product(self, request: CreateProductRequest) -> Product:
13
        """
14
        Creates a product in the catalog.
15
        
16
        Args:
17
            request: Contains parent (catalog/branch path), product data, and product_id
18
            
19
        Returns:
20
            Product: The created product with generated name and metadata
21
            
22
        Raises:
23
            AlreadyExists: If product_id already exists
24
            InvalidArgument: If required fields are missing or invalid
25
        """
26

27
    def get_product(self, request: GetProductRequest) -> Product:
28
        """
29
        Retrieves a product by its resource name.
30
        
31
        Args:
32
            request: Contains name (full product resource path)
33
            
34
        Returns:
35
            Product: The requested product
36
            
37
        Raises:
38
            NotFound: If product doesn't exist
39
        """
40

41
    def list_products(self, request: ListProductsRequest) -> ListProductsResponse:
42
        """
43
        Lists products in a catalog branch with optional filtering.
44
        
45
        Args:
46
            request: Contains parent path, page_size, page_token, filter, read_mask
47
            
48
        Returns:
49
            ListProductsResponse: Products and next_page_token for pagination
50
        """
51

52
    def update_product(self, request: UpdateProductRequest) -> Product:
53
        """
54
        Updates an existing product.
55
        
56
        Args:
57
            request: Contains product data and update_mask for partial updates
58
            
59
        Returns:
60
            Product: The updated product
61
            
62
        Raises:
63
            NotFound: If product doesn't exist
64
        """
65

66
    def delete_product(self, request: DeleteProductRequest) -> None:
67
        """
68
        Deletes a product from the catalog.
69
        
70
        Args:
71
            request: Contains name (product resource path)
72
            
73
        Raises:
74
            NotFound: If product doesn't exist
75
        """
76

77
class ProductServiceAsyncClient:
78
    async def create_product(self, request: CreateProductRequest) -> Product:
79
        """Async version of create_product."""
80
    
81
    async def get_product(self, request: GetProductRequest) -> Product:
82
        """Async version of get_product."""
83
    
84
    async def list_products(self, request: ListProductsRequest) -> ListProductsResponse:
85
        """Async version of list_products."""
86
    
87
    async def update_product(self, request: UpdateProductRequest) -> Product:
88
        """Async version of update_product."""
89
    
90
    async def delete_product(self, request: DeleteProductRequest) -> None:
91
        """Async version of delete_product."""
92
```
93

94
### Inventory Management
95

96
Operations for managing product inventory, availability, and fulfillment locations.
97

98
```python { .api }
99
class ProductServiceClient:
100
    def set_inventory(self, request: SetInventoryRequest) -> Operation:
101
        """
102
        Updates product inventory information (long-running operation).
103
        
104
        Args:
105
            request: Contains inventory data, set_mask, and optional set_time
106
            
107
        Returns:
108
            Operation: Long-running operation that resolves to SetInventoryResponse
109
        """
110

111
    def add_fulfillment_places(self, request: AddFulfillmentPlacesRequest) -> Operation:
112
        """
113
        Adds fulfillment places to a product (long-running operation).
114
        
115
        Args:
116
            request: Contains product name, type, place_ids, and add_time
117
            
118
        Returns:
119
            Operation: Resolves to AddFulfillmentPlacesResponse
120
        """
121

122
    def remove_fulfillment_places(self, request: RemoveFulfillmentPlacesRequest) -> Operation:
123
        """
124
        Removes fulfillment places from a product (long-running operation).
125
        
126
        Args:
127
            request: Contains product name, type, place_ids, and remove_time
128
            
129
        Returns:
130
            Operation: Resolves to RemoveFulfillmentPlacesResponse
131
        """
132

133
    def add_local_inventories(self, request: AddLocalInventoriesRequest) -> Operation:
134
        """
135
        Adds local inventory information to a product (long-running operation).
136
        
137
        Args:
138
            request: Contains product name, local_inventories, and add_time
139
            
140
        Returns:
141
            Operation: Resolves to AddLocalInventoriesResponse
142
        """
143

144
    def remove_local_inventories(self, request: RemoveLocalInventoriesRequest) -> Operation:
145
        """
146
        Removes local inventory information from a product (long-running operation).
147
        
148
        Args:
149
            request: Contains product name, place_ids, and remove_time
150
            
151
        Returns:
152
            Operation: Resolves to RemoveLocalInventoriesResponse
153
        """
154

155
class ProductServiceAsyncClient:
156
    async def set_inventory(self, request: SetInventoryRequest) -> Operation:
157
        """Async version of set_inventory."""
158
    
159
    async def add_fulfillment_places(self, request: AddFulfillmentPlacesRequest) -> Operation:
160
        """Async version of add_fulfillment_places."""
161
    
162
    async def remove_fulfillment_places(self, request: RemoveFulfillmentPlacesRequest) -> Operation:
163
        """Async version of remove_fulfillment_places."""
164
    
165
    async def add_local_inventories(self, request: AddLocalInventoriesRequest) -> Operation:
166
        """Async version of add_local_inventories."""
167
    
168
    async def remove_local_inventories(self, request: RemoveLocalInventoriesRequest) -> Operation:
169
        """Async version of remove_local_inventories."""
170
```
171

172
### Bulk Operations
173

174
Large-scale operations for importing and purging products in batches.
175

176
```python { .api }
177
class ProductServiceClient:
178
    def import_products(self, request: ImportProductsRequest) -> Operation:
179
        """
180
        Imports products in bulk from external sources (long-running operation).
181
        
182
        Args:
183
            request: Contains parent, input_config, errors_config, and update_mask
184
            
185
        Returns:
186
            Operation: Resolves to ImportProductsResponse with import statistics
187
        """
188

189
    def purge_products(self, request: PurgeProductsRequest) -> Operation:
190
        """
191
        Permanently deletes products matching filter criteria (long-running operation).
192
        
193
        Args:
194
            request: Contains parent, filter, and force flag
195
            
196
        Returns:
197
            Operation: Resolves to PurgeProductsResponse with purge count
198
        """
199

200
class ProductServiceAsyncClient:
201
    async def import_products(self, request: ImportProductsRequest) -> Operation:
202
        """Async version of import_products."""
203
    
204
    async def purge_products(self, request: PurgeProductsRequest) -> Operation:
205
        """Async version of purge_products."""
206
```
207

208
## Data Types
209

210
### Product
211

212
Core product entity containing all product information and metadata.
213

214
```python { .api }
215
class Product:
216
    name: str  # Resource name (read-only)
217
    id: str    # Product ID (required)
218
    type: ProductType  # PRIMARY or VARIANT
219
    primary_product_id: str  # For variant products
220
    collection_member_ids: List[str]  # Related products
221
    gtin: str  # Global Trade Item Number
222
    categories: List[str]  # Product categories
223
    title: str  # Product title (required)
224
    brands: List[str]  # Brand names
225
    description: str  # Product description
226
    language_code: str  # Content language
227
    attributes: Dict[str, CustomAttribute]  # Custom attributes
228
    tags: List[str]  # Tags for organization
229
    price_info: PriceInfo  # Pricing information
230
    rating: Rating  # Average rating and review count
231
    available_time: Timestamp  # When product becomes available
232
    availability: ProductAvailability  # IN_STOCK, OUT_OF_STOCK, etc.
233
    available_quantity: int  # Quantity available
234
    fulfillment_info: List[FulfillmentInfo]  # Fulfillment options
235
    uri: str  # Product page URL
236
    images: List[Image]  # Product images
237
    audience: Audience  # Target audience
238
    color_info: ColorInfo  # Color information
239
    sizes: List[str]  # Available sizes
240
    materials: List[str]  # Materials used
241
    patterns: List[str]  # Patterns/designs
242
    conditions: List[str]  # Product conditions
243
    promotions: List[Promotion]  # Active promotions
244
    publish_time: Timestamp  # Publication time
245
    retrievable_fields: FieldMask  # Fields included in search
246
    variants: List[Product]  # Product variants (read-only)
247
    local_inventories: List[LocalInventory]  # Local inventory data
248
```
249

250
### Supporting Types
251

252
```python { .api }
253
class PriceInfo:
254
    currency_code: str  # ISO 4217 currency code (required)
255
    price: float  # Listed price
256
    original_price: float  # Original price before discounts
257
    cost: float  # Cost price
258
    price_effective_time: Timestamp  # When price becomes effective
259
    price_expire_time: Timestamp  # When price expires
260
    price_range: PriceInfoPriceRange  # Price range for variants
261

262
class CustomAttribute:
263
    text: List[str]  # Text values
264
    numbers: List[float]  # Numeric values
265
    searchable: bool  # Whether attribute is searchable
266
    indexable: bool  # Whether attribute is indexable
267

268
class FulfillmentInfo:
269
    type: str  # Fulfillment type (pickup-in-store, ship-to-store, etc.)
270
    place_ids: List[str]  # Location identifiers
271

272
class LocalInventory:
273
    place_id: str  # Store/location identifier
274
    price_info: PriceInfo  # Local pricing
275
    attributes: Dict[str, CustomAttribute]  # Local attributes
276
    fulfillment_types: List[str]  # Available fulfillment types
277

278
class Rating:
279
    rating_count: int  # Total number of ratings
280
    average_rating: float  # Average rating value
281
    rating_histogram: List[int]  # Rating distribution (1-5 stars)
282

283
class Image:
284
    uri: str  # Image URL
285
    height: int  # Image height in pixels
286
    width: int  # Image width in pixels
287
```
288

289
### Request Types
290

291
```python { .api }
292
class CreateProductRequest:
293
    parent: str  # Catalog branch path (required)
294
    product: Product  # Product to create (required)
295
    product_id: str  # Product ID (required)
296

297
class GetProductRequest:
298
    name: str  # Product resource name (required)
299

300
class ListProductsRequest:
301
    parent: str  # Catalog branch path (required)
302
    page_size: int  # Maximum products to return (default: 100, max: 1000)
303
    page_token: str  # Token for pagination
304
    filter: str  # Filter expression
305
    read_mask: FieldMask  # Fields to return
306

307
class UpdateProductRequest:
308
    product: Product  # Product with updates (required)
309
    update_mask: FieldMask  # Fields to update
310
    allow_missing: bool  # Create if product doesn't exist
311

312
class DeleteProductRequest:
313
    name: str  # Product resource name (required)
314

315
class SetInventoryRequest:
316
    inventory: Product  # Product with inventory updates (required)
317
    set_mask: FieldMask  # Inventory fields to update
318
    set_time: Timestamp  # When inventory change occurred
319
    allow_missing: bool  # Create product if doesn't exist
320

321
class ImportProductsRequest:
322
    parent: str  # Catalog branch path (required)
323
    request_id: str  # Unique request identifier
324
    input_config: ProductInputConfig  # Data source configuration
325
    errors_config: ImportErrorsConfig  # Error handling configuration
326
    update_mask: FieldMask  # Fields to update for existing products
327
    reconciliation_mode: ImportProductsRequestReconciliationMode  # How to handle existing products
328
    notification_pubsub_topic: str  # Pub/Sub topic for completion notification
329
```
330

331
## Usage Examples
332

333
### Creating a Product
334

335
```python
336
from google.cloud import retail
337

338
client = retail.ProductServiceClient()
339

340
# Create a product with comprehensive information
341
product = retail.Product(
342
    id="electronics-laptop-123",
343
    type=retail.Product.Type.PRIMARY,
344
    title="Gaming Laptop Pro 15",
345
    categories=["Electronics", "Computers", "Laptops"],
346
    brands=["TechBrand"],
347
    description="High-performance gaming laptop with advanced graphics",
348
    price_info=retail.PriceInfo(
349
        currency_code="USD",
350
        price=1299.99,
351
        original_price=1499.99
352
    ),
353
    availability=retail.Product.Availability.IN_STOCK,
354
    available_quantity=25,
355
    attributes={
356
        "screen_size": retail.CustomAttribute(text=["15.6 inches"]),
357
        "processor": retail.CustomAttribute(text=["Intel i7"]),
358
        "ram": retail.CustomAttribute(text=["16GB"]),
359
        "storage": retail.CustomAttribute(text=["512GB SSD"]),
360
        "color": retail.CustomAttribute(text=["Black"])
361
    },
362
    tags=["gaming", "high-performance", "laptop"],
363
    uri="https://example.com/products/gaming-laptop-pro-15"
364
)
365

366
request = retail.CreateProductRequest(
367
    parent="projects/my-project/locations/global/catalogs/default_catalog/branches/default_branch",
368
    product=product,
369
    product_id=product.id
370
)
371

372
created_product = client.create_product(request=request)
373
print(f"Created product: {created_product.name}")
374
```
375

376
### Updating Product Inventory
377

378
```python
379
from google.protobuf import field_mask_pb2
380

381
# Update inventory for a product
382
inventory_update = retail.Product(
383
    name="projects/my-project/locations/global/catalogs/default_catalog/branches/default_branch/products/electronics-laptop-123",
384
    availability=retail.Product.Availability.OUT_OF_STOCK,
385
    available_quantity=0
386
)
387

388
request = retail.SetInventoryRequest(
389
    inventory=inventory_update,
390
    set_mask=field_mask_pb2.FieldMask(paths=["availability", "available_quantity"])
391
)
392

393
operation = client.set_inventory(request=request)
394
print(f"Inventory update operation: {operation.name}")
395

396
# Wait for operation to complete
397
result = operation.result()
398
print(f"Inventory updated: {result}")
399
```
400

401
### Bulk Product Import
402

403
```python
404
# Import products from Google Cloud Storage
405
input_config = retail.ProductInputConfig(
406
    gcs_source=retail.GcsSource(
407
        input_uris=["gs://my-bucket/products/products.json"]
408
    )
409
)
410

411
errors_config = retail.ImportErrorsConfig(
412
    gcs_prefix="gs://my-bucket/errors/"
413
)
414

415
request = retail.ImportProductsRequest(
416
    parent="projects/my-project/locations/global/catalogs/default_catalog/branches/default_branch",
417
    input_config=input_config,
418
    errors_config=errors_config,
419
    reconciliation_mode=retail.ImportProductsRequest.ReconciliationMode.INCREMENTAL
420
)
421

422
operation = client.import_products(request=request)
423
print(f"Import operation: {operation.name}")
424

425
# Monitor operation progress
426
result = operation.result()
427
print(f"Import completed. Success count: {result.success_count}")
428
```