--- title: Historical events description: Query a timeline of historical events for your partner organization using the Partner API. api_version: 2026-07 api_name: partner source_url: html: https://shopify.dev/docs/api/partner/2026-07/historical-events md: https://shopify.dev/docs/api/partner/2026-07/historical-events.md --- # Historical events **Release candidate:** The `events` query and all supporting types are available in the `2026-07` release candidate and `unstable`. Use the root `events` query on the [Partner API](https://shopify.dev/docs/api/partner) 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`](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D/connections/PartnerEventConnection) with cursor-based pagination. The maximum page size is 250. Requests with `first` greater than 250 return an error: ```graphql events( filter: EventFilterInput, orderBy: EventOrder = OCCURRED_AT_DESC, first: Int, after: String, last: Int, before: String ): PartnerEventConnection ``` *** ## Access requirements * The API client must have the **Manage apps** permission. See [Create a Partner API client](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D#create-a-partner-api-client). *** ## Filtering Events are filtered with the [`EventFilterInput`](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D/input-objects/EventFilterInput) type: | Field | Type | Description | | - | - | - | | `shopId` | `ID` | Filter to events for a single shop. Example: `gid://shopify/Shop/1234`. | | `subjectType` | [`SubjectType`](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D/enums/SubjectType) | Filter by subject product type. Currently only `APP` is supported. | | `subjectId` | `ID` | Filter to a single app. Example: `gid://shopify/App/1234`. | | `eventTypes` | `[EventType!]` | Filter to one or more event types (see [Event types](#event-types)). | | `occurredAtMin` | `DateTime` | Include events on or after this timestamp. | | `occurredAtMax` | `DateTime` | Include events on or before this timestamp. | ### Constraints * 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. ### Date 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. *** ## Ordering Results are ordered by `occurredAt` using the [`EventOrder`](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D/enums/EventOrder) argument: * **`OCCURRED_AT_DESC` (default)**: Newest first * **`OCCURRED_AT_ASC`**: Oldest first *** ## Event types Every event implements the [`PartnerEvent`](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D/interfaces/PartnerEvent) interface and exposes `id`, `occurredAt`, `eventType`, `subject` (the `App` the event applies to), and `shop`. The concrete type depends on `eventType`: | Concrete type | `EventType` values | Description | | - | - | - | | [`Relationship`](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D/objects/Relationship) | `RELATIONSHIP_INSTALLED`, `RELATIONSHIP_UNINSTALLED`, `RELATIONSHIP_DEACTIVATED`, `RELATIONSHIP_REACTIVATED` | Install, uninstall, or billing-account state change for an app. | | [`SubscriptionStatus`](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D/objects/SubscriptionStatus) | `SUBSCRIPTION_CREATED`, `SUBSCRIPTION_UPDATED`, `SUBSCRIPTION_CANCELED`, `SUBSCRIPTION_CANCELLATION_SCHEDULED`, `SUBSCRIPTION_FROZEN`, `SUBSCRIPTION_UNFROZEN` | Creation, update, cancellation, or freeze/unfreeze of a subscription. | | [`Charge`](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D/objects/Charge) | `CHARGE_ONE_TIME`, `CHARGE_RECURRING`, `CHARGE_USAGE` | The merchant was billed. | | [`Earning`](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D/objects/Earning) | `EARNING_CHARGE_ONE_TIME`, `EARNING_CHARGE_RECURRING`, `EARNING_CHARGE_USAGE`, `EARNING_REFUND`, `EARNING_ADJUSTMENT`, `EARNING_CREDIT` | The Partner received (or refunded) payment. | | [`Credit`](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D/objects/Credit) | `CREDIT_PENDING`, `CREDIT_APPLIED`, `CREDIT_FAILED` | A credit was issued, applied, or failed. | Use inline fragments to select fields on each concrete type. *** ## Example ## Historical events ##### Query: All event types ```graphql 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 } } } } } ``` ##### Variables — charges for a single app this month ```json { "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 } ``` ##### Variables — installs and uninstalls for one app on one shop ```json { "filter": { "subjectId": "gid://shopify/App/1234", "shopId": "gid://shopify/Shop/5678", "eventTypes": ["RELATIONSHIP_INSTALLED", "RELATIONSHIP_UNINSTALLED"] } } ``` *** ## Pagination 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`. **Info:** Requests with `first` greater than `250` return an error. Use `after: $cursor` with the `endCursor` from `pageInfo` to page through large result sets. *** ## Backfilled 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`](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D/objects/Charge) and [`Earning`](https://shopify.dev/docs/api/partner/%7BAPI_VERSION%7D/objects/Earning) exposes the original billing record ID so you can reconcile against prior reports. *** ## Error handling | Condition | Behavior | | - | - | | Date range exceeds 365 days | Returns a GraphQL execution error | | Feature not enabled for the organization | Returns a GraphQL execution error | | `first` greater than 250 | Returns a GraphQL execution error | | `shopId` provided without `subjectId` | Returns a GraphQL execution error: `You must specify a subjectId when filtering by shopId.` | ***