Historical events

Use the root events query on the Partner API to retrieve a timeline of historical events for the authenticated partner. The connection returns a union of event types, including Relationship, Charge, Earning, SubscriptionStatus, and Credit. These cover installs and uninstalls, billing, payouts, subscription state changes, and credits.

The query returns a PartnerEventConnection with cursor-based pagination. The maximum page size is 250. Requests with first greater than 250 return an error:

Anchor to Access requirementsAccess requirements

• The API client must have the Manage apps permission. See Create a Partner API client.

Anchor to FilteringFiltering

Events are filtered with the EventFilterInput type:

Anchor to ConstraintsConstraints

• If shopId is provided, subjectId is required. Omitting subjectId when shopId is set returns an error.
• If subjectType is not provided, the query returns only APP events.

Anchor to Date range behaviorDate range behavior

• If neither occurredAtMin nor occurredAtMax is provided, the API returns events from the last 30 days.
• If only occurredAtMin is provided, occurredAtMax defaults to the earlier of occurredAtMin + 30 days or now.
• If only occurredAtMax is provided, occurredAtMin defaults to occurredAtMax - 30 days.
• The maximum range between occurredAtMin and occurredAtMax is 365 days. Queries exceeding this range return an error.

Anchor to OrderingOrdering

Results are ordered by occurredAt using the EventOrder argument:

• OCCURRED_AT_DESC (default): Newest first
• OCCURRED_AT_ASC: Oldest first

Anchor to Event typesEvent types

Every event implements the PartnerEvent interface and exposes id, occurredAt, eventType, subject (the App the event applies to), and shop. The concrete type depends on eventType:

Use inline fragments to select fields on each concrete type.

Anchor to ExampleExample

query HistoricalEvents($filter: EventFilterInput, $cursor: String) {
  events(filter: $filter, orderBy: OCCURRED_AT_DESC, first: 100, after: $cursor) {
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    edges {
      cursor
      node {
        id
        occurredAt
        eventType
        shop {
          id
          myshopifyDomain
        }
        subject {
          ... on AppReference {
            id
            name
            apiKey
          }
        }
        ... on Relationship {
          state
          reason
          reasonDescription
        }
        ... on SubscriptionStatus {
          state
          cancelEffectiveOn
          plan {
            handle
            billingPeriod
            trialDays
            trialDaysRemaining
            prices {
              __typename
              currencyCode
              ... on FlatRatePlanPrice {
                amount
              }
              ... on TieredPlanPrice {
                tiersMode
                tiers {
                  upTo
                  amountPerUnit
                  amount
                }
              }
            }
          }
        }
        ... on Charge {
          chargeId
          chargeType
          amount {
            amount
            currencyCode
          }
          usageQuantity
          planHandle
          balanceUsed
          description
          metadata {
            legacyChargeId
          }
        }
        ... on Earning {
          earningType
          chargeId
          grossAmount {
            amount
            currencyCode
          }
          netAmount {
            amount
            currencyCode
          }
          shopifyFee {
            amount
            currencyCode
          }
          settlementDate
          description
        }
        ... on Credit {
          status
          money {
            amount
            currencyCode
          }
          description
        }
      }
    }
  }
}

{
  "filter": {
    "subjectType": "APP",
    "subjectId": "gid://shopify/App/1234",
    "eventTypes": ["CHARGE_ONE_TIME", "CHARGE_RECURRING", "CHARGE_USAGE"],
    "occurredAtMin": "2026-04-01T00:00:00Z",
    "occurredAtMax": "2026-04-30T23:59:59Z"
  },
  "cursor": null
}

{
  "filter": {
    "subjectId": "gid://shopify/App/1234",
    "shopId": "gid://shopify/Shop/5678",
    "eventTypes": ["RELATIONSHIP_INSTALLED", "RELATIONSHIP_UNINSTALLED"]
  }
}

Anchor to PaginationPagination

Use cursor-based pagination with first and after (forward) or last and before (backward). The maximum page size is 250. The pageInfo object exposes hasNextPage, hasPreviousPage, startCursor, and endCursor.

Anchor to Backfilled eventsBackfilled events

Some events represent charges that were originally created through the legacy Billing API and later backfilled into the historical events system. For these events, the metadata.legacyChargeId field on Charge and Earning exposes the original billing record ID so you can reconcile against prior reports.

Anchor to Error handlingError handling