La API de Merchant Reports te permite recuperar de forma programática las métricas de rendimiento de confirmación de compra y conversión del Universal Commerce Protocol (UCP) en las plataformas de Google, incluidos el Modo IA en la Búsqueda y Gemini. Estos informes proporcionan las mismas estadísticas de rendimiento disponibles en el panel de estadísticas de UCP de Merchant Center, lo que te ayuda a supervisar los embudos de conversión, los pedidos completados, las transferencias de carritos y la participación a nivel del producto.
La API secundaria de informes proporciona dos vistas para analizar el rendimiento de las UCP:
UcpAgenticPerformanceView(ucp_agentic_performance_view): Proporciona métricas de embudo de conversiones, pedidos, cancelaciones y transferencias de carritos a nivel de la cuenta segmentadas por fecha y país del cliente.UcpAgenticProductPerformanceView(ucp_agentic_product_performance_view): Proporciona métricas de clics en el botón de compra a nivel del producto (offer_id) segmentadas por fecha y país del cliente.
Antes de comenzar
Antes de consultar las vistas de rendimiento de UCP, asegúrate de cumplir con los siguientes requisitos:
- Usa el extremo
v1alpha: Envía tus consultas de MCQL al métodov1alphaaccounts.reports.search. Para obtener detalles sobre cómo ejecutar solicitudes de informes, consulta la página para comenzar a usar la API de Merchant Reports. - Tipos de cuentas admitidos: Tanto
ucp_agentic_performance_viewcomoucp_agentic_product_performance_viewadmiten cuentas de hoja (cuentas independientes y cuentas secundarias individuales), así como cuentas avanzadas (cuentas de varios clientes o cuentas de agregador). Para obtener detalles y ejemplos, consulta Cómo realizar consultas a nivel de la cuenta avanzada. - Filtro de fecha obligatorio: Debes especificar una condición en
dateen la cláusulaWHEREde cada consulta para ambas vistas.
Analiza el rendimiento de las UCP a nivel de la cuenta
Usa ucp_agentic_performance_view para hacer un seguimiento de tu embudo de conversión general de UCP, desde los clics en el botón de compra y la vinculación de cuentas hasta las compras completadas y las transferencias de carritos.
Métricas de moneda y precio
ucp_agentic_performance_view controla las métricas de moneda y Price de la misma manera que los informes de rendimiento:
- Métricas
Price: Las siguientes métricas devuelven un objetoPriceque contiene un valoramount_microsy uncurrency_code:purchase_valueaverage_order_valueaverage_purchase_product_valueaverage_cart_valueaverage_cart_product_value
- Métricas que no son de precio: Las siguientes métricas no tienen una moneda asociada:
buy_button_clicksaccounts_linkedaccount_linking_ratepurchase_countcancellationsaverage_purchase_product_countcart_transfersaverage_cart_product_count
- Métricas generales de embudo y recuento (independientes de la moneda): Selecciona solo las métricas que no sean de precio para obtener recuentos agregados independientes de la moneda.
- Métricas de valor de compra y del carrito (por moneda): Selecciona las métricas de
Pricejunto con sus recuentos de pedidos y carritos correspondientes para analizar los ingresos y el valor por moneda.
Consulta 1: Recupera las métricas generales del embudo (independientes de la moneda)
Usa la siguiente consulta para recuperar las métricas generales del embudo de conversiones, el recuento de pedidos y la transferencia del carrito, independientemente de la moneda (sin incluir las métricas de valor de Price):
SELECT
date,
account_id,
customer_country_code,
buy_button_clicks,
accounts_linked,
account_linking_rate,
purchase_count,
cancellations,
average_purchase_product_count,
cart_transfers,
average_cart_product_count
FROM ucp_agentic_performance_view
WHERE date = '2026-09-20'
La respuesta devuelve métricas de embudo agregadas para cada país del cliente:
{
"results": [
{
"ucpAgenticPerformanceView": {
"date": {
"year": 2026,
"month": 9,
"day": 20
},
"accountId": "123456789",
"customerCountryCode": "US",
"buyButtonClicks": "420",
"accountsLinked": "85",
"accountLinkingRate": 0.68,
"purchaseCount": "64",
"cancellations": "3",
"averagePurchaseProductCount": 1.75,
"cartTransfers": "52",
"averageCartProductCount": 2.1
}
}
]
}
Consulta 2: Recupera las métricas de compras y del valor del carrito (por moneda)
Usa la siguiente consulta para recuperar los valores de compra, los valores promedio de los pedidos y los valores de transferencia del carrito segmentados por moneda:
SELECT
date,
account_id,
customer_country_code,
purchase_count,
purchase_value,
average_order_value,
average_purchase_product_count,
average_purchase_product_value,
average_cart_value,
average_cart_product_value
FROM ucp_agentic_performance_view
WHERE date = '2026-09-20' AND purchase_count > 0
La respuesta devuelve una fila independiente para cada moneda presente en las métricas de valor de compra o del carrito:
{
"results": [
{
"ucpAgenticPerformanceView": {
"date": {
"year": 2026,
"month": 9,
"day": 20
},
"accountId": "123456789",
"customerCountryCode": "US",
"purchaseCount": "64",
"purchaseValue": {
"amountMicros": "5120000000",
"currencyCode": "USD"
},
"averageOrderValue": {
"amountMicros": "80000000",
"currencyCode": "USD"
},
"averagePurchaseProductCount": 1.75,
"averagePurchaseProductValue": {
"amountMicros": "45714285",
"currencyCode": "USD"
},
"cartTransfers": "52",
"averageCartValue": {
"amountMicros": "94500000",
"currencyCode": "USD"
},
"averageCartProductCount": 2.1,
"averageCartProductValue": {
"amountMicros": "45000000",
"currencyCode": "USD"
}
}
}
]
}
Analiza el rendimiento de las UCP a nivel del producto
Usa ucp_agentic_product_performance_view para ver qué productos individuales reciben clics en el botón de compra directamente desde las plataformas de Google.
Recupera los clics en el botón de compra por producto
Usa la siguiente consulta para recuperar los clics en el botón de compra a nivel del producto para una fecha específica:
SELECT
date,
account_id,
customer_country_code,
offer_id,
title,
buy_button_clicks
FROM ucp_agentic_product_performance_view
WHERE date = '2026-09-20'
También puedes omitir date de la cláusula SELECT para agregar clics en un
período con BETWEEN:
SELECT
account_id,
customer_country_code,
offer_id,
title,
buy_button_clicks
FROM ucp_agentic_product_performance_view
WHERE date BETWEEN '2026-09-01' AND '2026-09-20'
ORDER BY buy_button_clicks DESC
La respuesta devuelve los clics agregados en el botón de compra para cada oferta coincidente:
{
"results": [
{
"ucpAgenticProductPerformanceView": {
"accountId": "123456789",
"customerCountryCode": "US",
"offerId": "sku-10042",
"title": "Lightweight Running Shoes - Blue / Size 10",
"buyButtonClicks": "38"
}
}
]
}
Consulta a nivel de la cuenta avanzada
Puedes consultar ucp_agentic_performance_view y
ucp_agentic_product_performance_view especificando una
cuenta avanzada
(cuenta de varios clientes o cuenta de agregador) en el parámetro parent de la
solicitud
accounts.reports.search, como accounts/{advanced_account_id}.
En ambas vistas, la columna account_id siempre contiene el ID de cuenta de Merchant Center hoja (el ID de cuenta secundaria individual cuando se realiza una consulta en una cuenta avanzada o el ID de cuenta independiente cuando se realiza una consulta en una cuenta independiente). Cuando realizas consultas a nivel de la cuenta avanzada, el hecho de que incluyas account_id en la cláusula SELECT determina cómo se agrupan las métricas:
- Omite
account_id(agregado a nivel de la cuenta avanzada): Cuando no se seleccionaaccount_id, la respuesta agrega métricas en todas las cuentas secundarias que pertenecen a la cuenta avanzada. - Selecciona
account_id(desglosado por cuenta secundaria): Cuando se seleccionaaccount_id, la respuesta segmenta las estadísticas poraccount_idde hoja y devuelve filas separadas para cada cuenta secundaria de la cuenta avanzada.
Recupera métricas agregadas en una cuenta avanzada
Para recuperar las métricas totales del embudo de UCP consolidadas a nivel de la cuenta avanzada,
envía la solicitud con el ID de tu cuenta avanzada como el recurso parent y
omite account_id de la cláusula SELECT:
SELECT
date,
customer_country_code,
buy_button_clicks,
accounts_linked,
account_linking_rate,
purchase_count,
cancellations
FROM ucp_agentic_performance_view
WHERE date = '2026-09-20'
La respuesta devuelve una sola fila agregada por fecha y país del cliente en todas las cuentas secundarias de la cuenta avanzada:
{
"results": [
{
"ucpAgenticPerformanceView": {
"date": {
"year": 2026,
"month": 9,
"day": 20
},
"customerCountryCode": "US",
"buyButtonClicks": "730",
"accountsLinked": "140",
"accountLinkingRate": 0.65,
"purchaseCount": "110",
"cancellations": "5"
}
}
]
}
Recupera métricas desglosadas por cuenta secundaria
Para desglosar los resultados por cuenta secundaria cuando consultes una cuenta avanzada,
incluye account_id en la cláusula SELECT:
SELECT
date,
account_id,
customer_country_code,
buy_button_clicks,
accounts_linked,
account_linking_rate,
purchase_count,
cancellations
FROM ucp_agentic_performance_view
WHERE date = '2026-09-20'
Como account_id siempre contiene el ID de cuenta de la cuenta de hoja, la respuesta devuelve una fila independiente para cada cuenta secundaria de la cuenta avanzada:
{
"results": [
{
"ucpAgenticPerformanceView": {
"date": {
"year": 2026,
"month": 9,
"day": 20
},
"accountId": "123456789",
"customerCountryCode": "US",
"buyButtonClicks": "420",
"accountsLinked": "85",
"accountLinkingRate": 0.68,
"purchaseCount": "64",
"cancellations": "3"
}
},
{
"ucpAgenticPerformanceView": {
"date": {
"year": 2026,
"month": 9,
"day": 20
},
"accountId": "987654321",
"customerCountryCode": "US",
"buyButtonClicks": "310",
"accountsLinked": "55",
"accountLinkingRate": 0.61,
"purchaseCount": "46",
"cancellations": "2"
}
}
]
}