Google Merchant Center

通过托管的 OAuth 认证访问 Google Merchant Center API。管理 Google Shopping 的产品、库存、促销活动、数据源和报告。

快速开始

# List products in your Merchant Center account
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-merchant/products/v1/accounts/{accountId}/products')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础 URL

https://gateway.maton.ai/google-merchant/{sub-api}/{version}/accounts/{accountId}/{resource}

Merchant API 采用模块化子 API 结构。将：

• {sub-api}替换为服务：products、accounts、datasources、reports、promotions、inventories、notifications、conversions
• {version}替换为v1
• {accountId}使用您的 Merchant Center 账户 ID

网关将请求代理至merchantapi.googleapis.com并自动注入您的 OAuth 令牌。

重要提示：v1 API 需要一次性开发者注册。请参阅开发者注册部分。

身份验证

所有请求都需要在 Authorization 请求头中包含 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：将您的 API 密钥设置为MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

1. 请登录或前往以下网址创建账户maton.ai
2. 前往maton.ai/settings
3. 复制您的 API 密钥

查找您的 Merchant Center 账户 ID

您的 Merchant Center 账户 ID 是一个数字标识符。查找方法如下：

1. 登录Google Merchant Center
2. 查看网址 - 其中包含您的账户 ID：https://merchants.google.com/mc/overview?a=账户ID

开发者注册

重要：在使用 v1 API 之前，您必须完成一次性开发者注册，将您的账户与 API 关联。

步骤 1：获取您的账户 ID

选项 A：首先尝试通过 API 获取

尝试使用 v1beta 端点列出账户。如果成功，您可以自动获取账户 ID：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-merchant/accounts/v1beta/accounts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
try:
    result = json.load(urllib.request.urlopen(req))
    for account in result.get('accounts', []):
        print(f"Account ID: {account['accountId']}, Name: {account['accountName']}")
except Exception as e:
    print(f"v1beta not available - use Option B to get your account ID manually")
EOF

选项 B：从 Merchant Center 界面获取（如果选项 A 失败）

如果 v1beta 端点不可用或返回错误：

1. 登录Google Merchant Center
2. 您的账户 ID 在网址中：https://merchants.google.com/mc/overview?a=您的账户ID

例如，如果您的网址是https://merchants.google.com/mc/overview?a=123456789，您的账户ID是123456789。

第2步：注册API访问权限

调用registerGcp端点，并附上您的账户ID和邮箱：

python <<'EOF'
import urllib.request, os, json

account_id = 'YOUR_ACCOUNT_ID'  # From Step 1
developer_email = 'your-email@example.com'  # Your Google account email

data = json.dumps({'developerEmail': developer_email}).encode()
req = urllib.request.Request(
    f'https://gateway.maton.ai/google-merchant/accounts/v1/accounts/{account_id}/developerRegistration:registerGcp',
    data=data,
    method='POST'
)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')

result = json.load(urllib.request.urlopen(req))
print(json.dumps(result, indent=2))
EOF

响应：

{
  "name": "accounts/123456789/developerRegistration",
  "gcpIds": ["216141799266"]
}

第3步：验证注册

注册完成后，v1端点将正常工作：

python <<'EOF'
import urllib.request, os, json
account_id = 'YOUR_ACCOUNT_ID'
req = urllib.request.Request(f'https://gateway.maton.ai/google-merchant/accounts/v1/accounts/{account_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

注意：每个Merchant Center账户只需注册一次。注册后，所有v1端点将对该账户生效。

连接管理

在https://ctrl.maton.ai管理您的Google Merchant OAuth连接。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-merchant&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'google-merchant'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "connection": {
    "connection_id": "00726960-095e-47e2-92e6-6e9cdf3e40a1",
    "status": "ACTIVE",
    "creation_time": "2026-02-07T06:41:22.751289Z",
    "last_updated_time": "2026-02-07T06:42:29.411979Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "google-merchant",
    "metadata": {}
  }
}

打开返回的网址在浏览器中完成 OAuth 授权。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果您有多个 Google Merchant 连接，请通过Maton-Connection标头指定要使用哪一个：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-merchant/products/v1/accounts/123456/products')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '00726960-095e-47e2-92e6-6e9cdf3e40a1')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用默认（最早建立的）活动连接。

API 参考

子 API 结构

Merchant API 按子 API 组织：

子 API	用途	版本
products	产品目录管理	v1
accounts	账户设置和用户	v1
datasources	数据源配置	v1
reports	分析与报告	v1
促销	促销优惠（需要注册）	v1
库存	本地和区域库存	v1
通知	Webhook 订阅	v1
转化	转化跟踪	v1

账户

列出账户

GET /google-merchant/accounts/v1/accounts

返回您的 OAuth 凭据可访问的所有 Merchant Center 账户。使用此功能查找您的账户 ID。

获取账户

GET /google-merchant/accounts/v1/accounts/{accountId}

列出子账户

GET /google-merchant/accounts/v1/accounts/{accountId}:listSubaccounts

注意：此端点仅适用于多客户账户 (MCA)。标准商家账户将收到 403 错误。

获取业务信息

GET /google-merchant/accounts/v1/accounts/{accountId}/businessInfo

更新业务信息

PATCH /google-merchant/accounts/v1/accounts/{accountId}/businessInfo?updateMask=customerService
Content-Type: application/json

{
  "customerService": {
    "email": "support@example.com"
  }
}

获取主页

GET /google-merchant/accounts/v1/accounts/{accountId}/homepage

获取配送设置

GET /google-merchant/accounts/v1/accounts/{accountId}/shippingSettings

插入配送设置

POST /google-merchant/accounts/v1/accounts/{accountId}/shippingSettings:insert
Content-Type: application/json

{
  "services": [
    {
      "serviceName": "Standard Shipping",
      "deliveryCountries": ["US"],
      "currencyCode": "USD",
      "deliveryTime": {
        "minTransitDays": 3,
        "maxTransitDays": 7,
        "minHandlingDays": 0,
        "maxHandlingDays": 1
      },
      "rateGroups": [
        {
          "singleValue": {
            "flatRate": {
              "amountMicros": "0",
              "currencyCode": "USD"
            }
          }
        }
      ],
      "active": true
    }
  ]
}

列出用户

GET /google-merchant/accounts/v1/accounts/{accountId}/users

获取用户

GET /google-merchant/accounts/v1/accounts/{accountId}/users/{email}

列出项目

GET /google-merchant/accounts/v1/accounts/{accountId}/programs

列出区域

GET /google-merchant/accounts/v1/accounts/{accountId}/regions

列出账户问题

GET /google-merchant/accounts/v1/accounts/{accountId}/issues

列出在线退货政策

GET /google-merchant/accounts/v1/accounts/{accountId}/onlineReturnPolicies

产品

列出产品

GET /google-merchant/products/v1/accounts/{accountId}/products

查询参数：

• 每页大小（整数）：每页最大结果数
• 页面令牌（字符串）：分页令牌

获取产品

GET /google-merchant/products/v1/accounts/{accountId}/products/{productId}

产品ID格式：内容语言~源标签~商品ID（例如，en~US~sku123）

插入产品输入

POST /google-merchant/products/v1/accounts/{accountId}/productInputs:insert?dataSource=accounts/{accountId}/dataSources/{dataSourceId}
Content-Type: application/json

{
  "offerId": "sku123",
  "contentLanguage": "en",
  "feedLabel": "US",
  "productAttributes": {
    "title": "Product Title",
    "description": "Product description",
    "link": "https://example.com/product",
    "imageLink": "https://example.com/image.jpg",
    "availability": "in_stock",
    "price": {
      "amountMicros": "19990000",
      "currencyCode": "USD"
    },
    "condition": "new"
  }
}

注意：产品只能插入到具有输入："API"类型的数据源中。如有需要，请先创建一个API数据源。

删除产品输入

DELETE /google-merchant/products/v1/accounts/{accountId}/productInputs/{productId}?dataSource=accounts/{accountId}/dataSources/{dataSourceId}

库存

列出本地库存

GET /google-merchant/inventories/v1/accounts/{accountId}/products/{productId}/localInventories

注意：本地库存仅适用于具有LOCAL渠道的产品。请使用类似local~en~US~sku123的产品ID。

插入本地库存

POST /google-merchant/inventories/v1/accounts/{accountId}/products/{productId}/localInventories:insert
Content-Type: application/json

{
  "storeCode": "store123"
}

注意：storeCode必须是您在Merchant Center账户中配置的有效店铺代码。可能还有其他库存属性可用 - 请参阅Google Merchant API参考文档以获取完整字段列表。列出区域库存

数据源

GET /google-merchant/inventories/v1/accounts/{accountId}/products/{productId}/regionalInventories

列出数据源

List Data Sources

GET /google-merchant/datasources/v1/accounts/{accountId}/dataSources

获取数据源

GET /google-merchant/datasources/v1/accounts/{accountId}/dataSources/{dataSourceId}

创建数据源

POST /google-merchant/datasources/v1/accounts/{accountId}/dataSources
Content-Type: application/json

{
  "displayName": "API Data Source",
  "primaryProductDataSource": {
    "feedLabel": "US",
    "contentLanguage": "en"
  }
}

响应：

{
  "name": "accounts/123456/dataSources/789",
  "dataSourceId": "789",
  "displayName": "API Data Source",
  "primaryProductDataSource": {
    "feedLabel": "US",
    "contentLanguage": "en"
  },
  "input": "API"
}

更新数据源

PATCH /google-merchant/datasources/v1/accounts/{accountId}/dataSources/{dataSourceId}?updateMask=displayName
Content-Type: application/json

{
  "displayName": "Updated Name"
}

删除数据源

DELETE /google-merchant/datasources/v1/accounts/{accountId}/dataSources/{dataSourceId}

获取数据源（触发即时刷新）

POST /google-merchant/datasources/v1/accounts/{accountId}/dataSources/{dataSourceId}:fetch

注意：获取操作仅适用于输入类型为文件的数据源。API和UI数据源无法获取。

报告

搜索报告

POST /google-merchant/reports/v1/accounts/{accountId}/reports:search
Content-Type: application/json

{
  "query": "SELECT offer_id, title, clicks, impressions FROM product_performance_view WHERE date BETWEEN '2026-01-01' AND '2026-01-31'"
}

示例：查询product_view（需要id字段）：

{
  "query": "SELECT id, offer_id, title, item_issues FROM product_view LIMIT 10"
}

注意：product_view表要求SELECT子句中包含id字段。可用报告表：

product_performance_view

• - 按产品统计的点击量、展示量、点击率- Clicks, impressions, CTR by product
• 产品视图- 包含属性和问题的当前库存（SELECT 中需要id）
• 价格竞争力产品视图- 与竞争对手的定价对比（需要市场洞察）
• 定价洞察产品视图- 建议定价
• 畅销产品集群视图- 按类别划分的畅销品（需要市场洞察）
• 竞争对手可见性视图- 竞争对手可见性

促销活动

注意：促销活动要求您的商家中心账户已加入促销计划。如果未加入，您将收到 403 错误。

列出促销活动

GET /google-merchant/promotions/v1/accounts/{accountId}/promotions

获取促销活动

GET /google-merchant/promotions/v1/accounts/{accountId}/promotions/{promotionId}

插入促销活动

POST /google-merchant/promotions/v1/accounts/{accountId}/promotions:insert
Content-Type: application/json

{
  "promotionId": "promo123",
  "contentLanguage": "en",
  "targetCountry": "US",
  "redemptionChannel": ["ONLINE"],
  "attributes": {
    "longTitle": "20% off all products",
    "promotionEffectiveDates": "2026-02-01T00:00:00Z/2026-02-28T23:59:59Z"
  }
}

通知

列出通知订阅

GET /google-merchant/notifications/v1/accounts/{accountId}/notificationsubscriptions

创建通知订阅

POST /google-merchant/notifications/v1/accounts/{accountId}/notificationsubscriptions
Content-Type: application/json

{
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "callBackUri": "https://example.com/webhook",
  "allManagedAccounts": true
}

注意：您必须指定allManagedAccounts: true或targetAccount: "accounts/{accountId}"以指示订阅适用于哪些账户。

使用 targetAccount 的替代方案：

{
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "callBackUri": "https://example.com/webhook",
  "targetAccount": "accounts/123456789"
}

删除通知订阅

DELETE /google-merchant/notifications/v1/accounts/{accountId}/notificationsubscriptions/{subscriptionId}

转化来源

列出转化来源

GET /google-merchant/conversions/v1/accounts/{accountId}/conversionSources

创建转化来源

POST /google-merchant/conversions/v1/accounts/{accountId}/conversionSources
Content-Type: application/json

{
  "merchantCenterDestination": {
    "displayName": "My Conversion Source",
    "destination": "SHOPPING_ADS",
    "currencyCode": "USD",
    "attributionSettings": {
      "attributionLookbackWindowDays": 30,
      "attributionModel": "CROSS_CHANNEL_LAST_CLICK"
    }
  }
}

删除转化来源

DELETE /google-merchant/conversions/v1/accounts/{accountId}/conversionSources/{conversionSourceId}

分页

该API使用基于令牌的分页：

GET /google-merchant/products/v1/accounts/{accountId}/products?pageSize=50

响应包含nextPageToken当存在更多结果时：

{
  "products": [...],
  "nextPageToken": "CAE..."
}

使用该令牌获取下一页：

GET /google-merchant/products/v1/accounts/{accountId}/products?pageSize=50&pageToken=CAE...

代码示例

JavaScript

const accountId = '123456789';
const response = await fetch(
  `https://gateway.maton.ai/google-merchant/products/v1/accounts/${accountId}/products`,
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();

Python

import os
import requests

account_id = '123456789'
response = requests.get(
    f'https://gateway.maton.ai/google-merchant/products/v1/accounts/{account_id}/products',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
data = response.json()

注意事项

• 需要开发者注册- 您必须完成开发者注册每个Merchant Center账户在使用v1端点前，需完成一次
• 产品ID采用以下格式内容语言~Feed标签~报价ID（例如，en~US~sku123）
• 产品只能在数据源中插入/更新/删除，且该数据源需具有输入："API"类型
• 插入/更新产品后，可能需要几分钟处理时间，产品才会显示
• 货币值以微单位表示（除以1,000,000得到实际值）
• 本地库存仅适用于渠道为本地的产品（非在线）
• 使用促销API要求您的账户已加入促销计划
• 列出子账户功能仅适用于多客户账户（MCA）
• 重要提示：使用curl命令时，请使用curl -g当URL包含方括号时，用于禁用通配符解析
• 重要提示：当将curl输出通过管道传递给jq或其他命令时，在某些shell环境中，像$MATON_API_KEY这样的环境变量可能无法正确展开

错误处理

状态码	含义
400	请求无效或缺少Google Merchant连接
401	Maton API密钥无效/缺失，或GCP项目未注册（参见开发者注册）
403	权限被拒绝 - 账户未注册所需项目或功能不可用
404	资源未找到
429	请求频率受限
4xx/5xx	来自Google Merchant API的透传错误

常见错误

"GCP 项目未注册"：您需要完成开发者注册。请参阅开发者注册章节。

"调用者无权访问账户"：您使用的 OAuth 凭据无法访问指定的账户 ID。请确认您有权访问该 Merchant Center 账户。

"促销计划未启用"：您的 Merchant Center 账户未加入促销计划。请在 Merchant Center 设置中启用。

"此方法仅限多客户端账户访问"：您正在调用一个仅适用于多客户端账户（MCA）的端点（例如 listSubaccounts）。

"渠道不匹配"：您正尝试访问 ONLINE 产品的本地库存。本地库存仅适用于 LOCAL 渠道的产品。

故障排除：API 密钥问题

1. 检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

2. 通过列出连接来验证 API 密钥是否有效：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排除：应用名称无效

确保您的 URL 路径以google-merchant开头。例如：

• 正确示例：https://gateway.maton.ai/google-merchant/products/v1/accounts/{accountId}/products
• 错误示例：https://gateway.maton.ai/products/v1/accounts/{accountId}/products

故障排除：401 GCP 项目未注册

如果您看到类似“GCP 项目未在商家账户中注册”的错误：

1. 完成开发者注册- 参见开发者注册部分
2. 从 Merchant Center UI 获取您的账户 ID（在 URL 中?a=之后的部分）
3. 调用registerGcp端点，并提供您的账户 ID 和电子邮件
4. 注册成功后，请重试您的原始请求

资源

• 商户API概览
• 商户API参考
• 产品指南
• 数据源指南
• 报告指南
• 产品数据规范
• Maton社区
• Maton支持

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。