Contextual History

In this example we take you through how query for the contextual history of a number of different entity types.

3 minute read

What you’ll learn

In this you’ll learn:

What is contextual history
What items have a contextual history
How to query contextual history using the Operator API

Note

The contextualHistory query is only available in the Operator API, and not available to sellers using the Seller API.

What is Contextual History

Think of contextual history as an audit log of events that have occurred on a given entity. For example you can:

Look at the update events on a Variant to look at the changes to sku, barcode, countOnHand etc.
Look ar the create event for Adverts to understand when they were first ingested into Marketplacer

The fields available for the ContextualHistory object are listed below:

Field	Data Type	Description
`changes`	JSON	A collection of changes on a given object field (e.g. `Sku` ot `Barcode`) with a `previous` and `new` values.
`createdAt`	ISO8601DateTime!	The timestamp when the event occured
`event`	String!	1 of 3 event types: `create`, `update` or `destroy`
`id`	ID!	The unique identifier for the event (in Base 64)
`itemId`	Int!	The unique identifier of the entity / item impacted by the change
`itemType`	String!	The type of entity that was impacted refer to the What items have a contextual history for a full list of the items
`origin`	String	What emitted the event, e.g. was it a system component, and API call or a user interaction.
`whodunnit`	String	In the case of a human generated event, the id of the user
`whodunnitType`	String	In the case of a human generated event, the type of user account

What items have a contextual history

The following items can have a contextual history:

Address
Admin
Advert
AccountSettings
AdvertSettings
CustomisationSettings
EcommerceSettings
ExternalAccountSettings
Invoice
InvoiceAmendment
InvoiceAmendmentLineItem
InvoiceAnnotation
LineItem
RefundRequest
RefundRequestLineItem
RefundRequestNote
Email
PricingDetail
Shipment
Subscription
User
Variant

You can supply these values as a filter to the contextualHistory query when you want to narrow down your search.

Using the `contextualHistory` query

Please refer to our GraphQL Best Practices Guide when writing queries for production systems.

Below we have provided a few examples of how to use the contextualHistory query.

Example 1: Query for all events and entities created after a given time

query ContextualHistorySince {
  contextualHistory(
    first: 100
    after: null
    createdAt: { gt: "2024-03-06T02:30:12+11:00" }
  ) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    nodes {
      createdAt
      changes
      event
      id
      itemId
      itemType
      origin
      whodunnit
      whodunnitType
    }
  }
}

Example 2: Query for all `update` events on the `Variant` item type

query ContextualHistorySince {
  contextualHistory(
    first: 100
    after: null
    itemType: "Variant"
    event: "update"
  ) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    nodes {
      createdAt
      changes
      event
      id
      itemId
      itemType
      origin
      whodunnit
      whodunnitType
    }
  }
}