0
# Google Shopping Merchant Conversions
1

2
Google Shopping Merchant Conversions API client library for Python, providing programmatic access to manage conversion sources and track conversions within Google's shopping ecosystem. This library enables developers to integrate merchant account management, conversion tracking, and attribution settings into their e-commerce applications.
3

4
## Package Information
5

6
- **Package Name**: google-shopping-merchant-conversions
7
- **Language**: Python  
8
- **Installation**: `pip install google-shopping-merchant-conversions`
9
- **Documentation**: https://googleapis.dev/python/google-shopping-merchant-conversions/latest
10

11
## Core Imports
12

13
```python
14
# Main stable API (recommended)
15
from google.shopping import merchant_conversions_v1
16

17
# Alternative imports for specific components
18
from google.shopping.merchant_conversions_v1 import ConversionSourcesServiceClient
19
from google.shopping.merchant_conversions_v1 import ConversionSourcesServiceAsyncClient
20

21
# For beta features (identical to v1)
22
from google.shopping import merchant_conversions_v1beta
23
```
24

25
## Basic Usage
26

27
```python
28
from google.shopping import merchant_conversions_v1
29

30
# Create client with default credentials
31
client = merchant_conversions_v1.ConversionSourcesServiceClient()
32

33
# List conversion sources for a merchant account  
34
parent = "accounts/{account_id}"
35
request = merchant_conversions_v1.ListConversionSourcesRequest(parent=parent)
36
response = client.list_conversion_sources(request=request)
37

38
for conversion_source in response.conversion_sources:
39
    print(f"Name: {conversion_source.name}")
40
    print(f"State: {conversion_source.state}")
41

42
# Get a specific conversion source
43
name = "accounts/{account_id}/conversionSources/{conversion_source_id}"
44
request = merchant_conversions_v1.GetConversionSourceRequest(name=name)
45
conversion_source = client.get_conversion_source(request=request)
46
print(f"Retrieved: {conversion_source.name}")
47
```
48

49
## Authentication
50

51
Requires Google Cloud authentication:
52

53
```python
54
from google.oauth2 import service_account
55
from google.shopping import merchant_conversions_v1
56

57
# Using service account credentials
58
credentials = service_account.Credentials.from_service_account_file(
59
    "path/to/service-account-file.json")
60
client = merchant_conversions_v1.ConversionSourcesServiceClient(credentials=credentials)
61

62
# Using Application Default Credentials (ADC)
63
client = merchant_conversions_v1.ConversionSourcesServiceClient()
64
```
65

66
## Architecture
67

68
The library follows Google's GAPIC (Generated API Client) pattern:
69

70
- **Service Clients**: Main interfaces for API operations (sync and async versions)
71
- **Request/Response Messages**: Structured data types for API communication
72
- **Transport Layer**: Supports gRPC (default), gRPC AsyncIO, and REST protocols
73
- **Authentication**: Integrated with Google Cloud Identity and Access Management
74
- **Error Handling**: Standard Google API Core exceptions with retry logic
75

76
## Capabilities
77

78
### Conversion Sources Service
79

80
Core service client for managing conversion sources, supporting full CRUD operations with sync and async variants. Handles merchant account conversion tracking configuration.
81

82
```python { .api }
83
class ConversionSourcesServiceClient:
84
    def create_conversion_source(self, request: CreateConversionSourceRequest) -> ConversionSource: ...
85
    def update_conversion_source(self, request: UpdateConversionSourceRequest) -> ConversionSource: ...
86
    def delete_conversion_source(self, request: DeleteConversionSourceRequest) -> None: ...
87
    def undelete_conversion_source(self, request: UndeleteConversionSourceRequest) -> ConversionSource: ...
88
    def get_conversion_source(self, request: GetConversionSourceRequest) -> ConversionSource: ...
89
    def list_conversion_sources(self, request: ListConversionSourcesRequest) -> ListConversionSourcesResponse: ...
90

91
class ConversionSourcesServiceAsyncClient:
92
    async def create_conversion_source(self, request: CreateConversionSourceRequest) -> ConversionSource: ...
93
    async def update_conversion_source(self, request: UpdateConversionSourceRequest) -> ConversionSource: ...
94
    async def delete_conversion_source(self, request: DeleteConversionSourceRequest) -> None: ...
95
    async def undelete_conversion_source(self, request: UndeleteConversionSourceRequest) -> ConversionSource: ...
96
    async def get_conversion_source(self, request: GetConversionSourceRequest) -> ConversionSource: ...
97
    async def list_conversion_sources(self, request: ListConversionSourcesRequest) -> ListConversionSourcesResponse: ...
98
```
99

100
[Conversion Sources Service](./conversion-sources-service.md)
101

102
### Data Types and Messages
103

104
Core data structures for conversion sources, attribution settings, and API request/response messages. Includes enums for states, controllers, and attribution models.
105

106
```python { .api }
107
class ConversionSource:
108
    name: str
109
    state: ConversionSource.State
110
    expire_time: timestamp_pb2.Timestamp
111
    controller: ConversionSource.Controller
112
    google_analytics_link: GoogleAnalyticsLink  # oneof
113
    merchant_center_destination: MerchantCenterDestination  # oneof
114

115
class AttributionSettings:
116
    attribution_lookback_window_days: int
117
    attribution_model: AttributionSettings.AttributionModel
118
    conversion_type: List[AttributionSettings.ConversionType]
119

120
class GoogleAnalyticsLink:
121
    property_id: int
122
    attribution_settings: AttributionSettings
123

124
class MerchantCenterDestination:
125
    destination: str
126
    attribution_settings: AttributionSettings
127
```
128

129
[Data Types and Messages](./data-types.md)
130

131
### Resource Path Helpers
132

133
Utility methods for constructing and parsing Google Cloud resource paths. Essential for proper resource identification across the Google Cloud ecosystem.
134

135
```python { .api }
136
@classmethod
137
def conversion_source_path(cls, account: str, conversion_source: str) -> str: ...
138

139
@staticmethod
140
def parse_conversion_source_path(path: str) -> Dict[str, str]: ...
141

142
@classmethod  
143
def common_project_path(cls, project: str) -> str: ...
144

145
@staticmethod
146
def parse_common_project_path(path: str) -> Dict[str, str]: ...
147
```
148

149
[Resource Path Helpers](./resource-paths.md)
150

151
## Error Handling
152

153
```python
154
from google.api_core import exceptions
155
from google.shopping import merchant_conversions_v1
156

157
client = merchant_conversions_v1.ConversionSourcesServiceClient()
158

159
try:
160
    request = merchant_conversions_v1.GetConversionSourceRequest(name="invalid")
161
    response = client.get_conversion_source(request=request)
162
except exceptions.NotFound:
163
    print("Conversion source not found")
164
except exceptions.PermissionDenied:
165
    print("Insufficient permissions")
166
except exceptions.GoogleAPICallError as e:
167
    print(f"API call failed: {e}")
168
```
169

170
## Pagination
171

172
```python
173
from google.shopping import merchant_conversions_v1
174

175
client = merchant_conversions_v1.ConversionSourcesServiceClient()
176
parent = "accounts/{account_id}"
177

178
# Manual pagination
179
request = merchant_conversions_v1.ListConversionSourcesRequest(
180
    parent=parent,
181
    page_size=10
182
)
183
response = client.list_conversion_sources(request=request)
184

185
# Auto-pagination
186
for conversion_source in client.list_conversion_sources(request=request):
187
    print(f"Processing: {conversion_source.name}")
188
```