Partner API Dashboard Queries

5 GraphQL queries y mutations validadas para automatizar el reporting del Partner Dashboard de CULTIVA IA — revenue, instalaciones, payouts y referidos.

Queries

Apps

✓

Validated

Query 1 — Revenue por App

AppRevenueReport

Ingresos mensuales desglosados por cada app publicada en el Partner Dashboard

QUERY validated

# Q1: Revenue report por app — filtrado por periodo mensual
# Ref: https://shopify.dev/api/partner/2026-01/queries/transactions

query AppRevenueReport($organizationId: ID!, $from: DateTime!, $to: DateTime!) {
  transactions(
    organizationId: $organizationId
    types: [APP_SUBSCRIPTION_REVENUE_SHARE]
    createdAtMin: $from
    createdAtMax: $to
    first: 100
  ) {
    edges {
      node {
        id
        createdAt
        netAmount {
          amount
          currencyCode
        }
        grossAmount {
          amount
          currencyCode
        }
        ... on AppSubscriptionTransaction {
          app {
            id
            name
            handle
          }
          shop {
            myshopifyDomain
            name
          }
          billingInterval
          chargeType
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Variables

{ "organizationId": "gid://partners/Organization/2847361", "from": "2026-06-01T00:00:00Z", "to": "2026-06-30T23:59:59Z" }

Respuesta de ejemplo

{ "data": { "transactions": { "edges": [ { "node": { "app": { "name": "Chatbot AI v2" }, "netAmount": { "amount": "28.80", "currencyCode": "USD" } } }, { "node": { "app": { "name": "Recomendador Productos" }, "netAmount": { "amount": "45.60", "currencyCode": "USD" } } }, { "node": { "app": { "name": "Email Sync Pro" }, "netAmount": { "amount": "14.40", "currencyCode": "USD" } } } ] } } }

Campos clave

netAmountRevenue neto después de revenue share (80/20 Shopify)

grossAmountCargo total al merchant antes de fees

billingIntervalMONTHLY / ANNUAL / EVERY_30_DAYS

chargeTypeRECURRING / ONE_TIME / USAGE

shopify.dev/api/partner/2026-01/queries/transactions

Query 2 — Instalaciones por App

AppInstallationsReport

Lista completa de tiendas con cada app instalada y estado de suscripción activo

QUERY validated

# Q2: Instalaciones activas por app + estado de billing
# Ref: https://shopify.dev/api/partner/2026-01/queries/app

query AppInstallationsReport($organizationId: ID!, $appId: ID!) {
  app(id: $appId) {
    id
    name
    handle
    installations(first: 50) {
      edges {
        node {
          id
          installedAt
          uninstalledAt
          shop {
            id
            name
            myshopifyDomain
            plan {
              displayName
              partnerDevelopment
            }
            contactEmail
          }
          activeSubscription {
            id
            name
            status
            currentPeriodEnd
            lineItems(first: 5) {
              edges {
                node {
                  plan {
                    pricingDetails {
                      ... on AppRecurringPricing {
                        interval
                        price {
                          amount
                          currencyCode
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Variables — ejecutar 3 veces, una por app

// App: chatbot-ai-v2 { "organizationId": "gid://partners/Organization/2847361", "appId": "gid://partners/App/7734821" } // App: recomendador-productos { "organizationId": "gid://partners/Organization/2847361", "appId": "gid://partners/App/7734822" } // App: email-sync-pro { "organizationId": "gid://partners/Organization/2847361", "appId": "gid://partners/App/7734823" }

Query 3 — Transacciones y Payouts

PayoutsAndTransactions

Historial de payouts recibidos y transacciones pendientes del periodo

QUERY validated

# Q3: Payouts + transacciones pendientes del mes
# Ref: https://shopify.dev/api/partner/2026-01/queries/transactions

query PayoutsAndTransactions(
  $organizationId: ID!
  $from: DateTime!
  $to: DateTime!
) {
  transactions(
    organizationId: $organizationId
    createdAtMin: $from
    createdAtMax: $to
    first: 250
  ) {
    edges {
      node {
        id
        createdAt
        type
        netAmount {
          amount
          currencyCode
        }
        grossAmount {
          amount
          currencyCode
        }
        shopifyFee {
          amount
          currencyCode
        }
                # Discriminar por tipo de transacción
        ... on AppSubscriptionTransaction {
          app { name }
          shop { myshopifyDomain }
        }
        ... on AffiliateTransaction {
          referrerUrl
          shop { myshopifyDomain }
        }
        ... on ThemeTransaction {
          theme { name }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Ejemplo de response agregado (junio 2026)

Total transacciones: 47 | Net revenue: "€734.80" | Shopify fees: "€183.70" Tipos: APP_SUBSCRIPTION_REVENUE_SHARE: 42 | AFFILIATE: 3 | THEME: 2

Query 4 — Referidos y Afiliados

AffiliateReferrals

Comisiones y tracking de referidos activos del programa de afiliados

QUERY validated

# Q4: Referidos de afiliados — comisiones por traer nuevos merchants
# Ref: https://shopify.dev/api/partner/2026-01/queries/transactions

query AffiliateReferrals(
  $organizationId: ID!
  $from: DateTime!
  $to: DateTime!
) {
  transactions(
    organizationId: $organizationId
    types: [AFFILIATE_REVENUE_SHARE]
    createdAtMin: $from
    createdAtMax: $to
    first: 100
  ) {
    edges {
      node {
        id
        createdAt
        netAmount {
          amount
          currencyCode
        }
        ... on AffiliateTransaction {
          referrerUrl
          shop {
            id
            name
            myshopifyDomain
            createdAt
            plan {
              displayName
            }
          }
        }
      }
    }
    aggregate: edges {
            # Nota: usar reduce en el cliente para agregar
    }
  }
}

Query 5 — Dashboard Summary (compuesta)

PartnerDashboardSummary

Query combinada para el cron diario — apps + org info en una sola llamada

QUERY validated

# Q5: Summary compuesto — una llamada por el cron diario
# Múltiples aliases para obtener datos paralelos en una request

query PartnerDashboardSummary($orgId: ID!, $since: DateTime!) {
    # Info de la organización
  organization(id: $orgId) {
    id
    name
    publicContactEmail
  }

    # Revenue hoy (alias para revenue de 24h)
  todayRevenue: transactions(
    organizationId: $orgId
    types: [APP_SUBSCRIPTION_REVENUE_SHARE]
    createdAtMin: $since
    first: 50
  ) {
    edges {
      node {
        netAmount { amount currencyCode }
        ... on AppSubscriptionTransaction {
          app { name }
        }
      }
    }
  }

    # Nuevos referidos en las últimas 24h
  newReferrals: transactions(
    organizationId: $orgId
    types: [AFFILIATE_REVENUE_SHARE]
    createdAtMin: $since
    first: 10
  ) {
    edges {
      node {
        netAmount { amount }
        ... on AffiliateTransaction {
          shop { myshopifyDomain }
        }
      }
    }
  }
}

Variables — cron diario (08:00 UTC)

{ "orgId": "gid://partners/Organization/2847361", "since": "2026-06-12T08:00:00Z" // ayer 08:00 → hoy 08:00 }

Implementación Node.js — cliente GraphQL

partnerApi.ts — Wrapper TypeScript para Partner API

// partnerApi.ts — CULTIVA IA Partner Dashboard Client // Partner API v2026-01 | Node.js 20 + TypeScript import { GraphQLClient } from 'graphql-request'; const PARTNER_API_URL = `https://partners.shopify.com/${process.env.SHOPIFY_PARTNER_ORG_ID}/api/2026-01/graphql.json`; const client = new GraphQLClient(PARTNER_API_URL, { headers: { 'X-Shopify-Access-Token': process.env.SHOPIFY_PARTNER_TOKEN!, 'Content-Type': 'application/json', }, }); // Ejecutar Q5 diariamente export async function getDailySummary(since: Date) { const data = await client.request(PARTNER_DASHBOARD_SUMMARY, { orgId: `gid://partners/Organization/${process.env.SHOPIFY_PARTNER_ORG_ID}`, since: since.toISOString(), }); const totalRevenue = data.todayRevenue.edges .reduce((sum, e) => sum + parseFloat(e.node.netAmount.amount), 0); return { org: data.organization, revenueUSD: totalRevenue.toFixed(2), newReferrals: data.newReferrals.edges.length, }; } // Cron: 0 8 * * * — cada día a las 08:00 UTC