node(s)

The node and nodes queries allow you to directly return objects by their Id. This can be useful when you want to return an individual object quickly (e.g. query an individual invoice)

  2 minute read  

Key Information

Use-Case

A node is a generic GraphQL object type that can be used to implement other concrete objects in the GraphQL schema, e.g. Order, Invoice etc. If a concrete object type implements node then we can query those objects directly using the node ID.

The node and nodes queries can be used to retrieve individual or collections of objects respectively. Use cases are many and varied but a node query could be used to return the individual inventory position of a product prior to checkout, whereas the nodes query could be used to return a collection of invoices for a given customer.

Further Points of Note

  • Most object types in the Marketplacer Seller API schema implement node
    • Only those objects that implement node can be used with the node and nodes queries
    • For a discussion on how to perform an introspection query to determine all the object types that implement node refer to this article.
  • Nodes can only be queried by their ID
  • Node is a generic type (actually an interface) so when using the node and nodes queries you need to specify the concrete class type that you want to return.
    • This is done via an inline fragment
    • Examples of this are provided below

Availability

  • Operator API: Yes
  • Seller API: Yes (Scoped to Seller-owned objects only)

Example (node)

query getProductById{
  node(id: "QWR2ZXJ0LTEwMDI4MzYzNQ==") {
    ... on Advert {
      id
      legacyId
      title
      lowestOriginalPrice
      lowestPrice
      baseDomesticShippingCost
      hasFreeDomesticShipping
      variants(displayableOnly: false){
        nodes{
          id
          label
        }
      }
    }
  }
}

Example (nodes)

query getProductsById{
  nodes(
    ids: [
      "SW52b2ljZS0xMDA1Mv=="
      "SW52b2ljZS0xMDA0Nw=="
      "SW52b2ljZS0xMVB2Ns=="
    ]
  ) {
    ... on Invoice {
      legacyId
      id
      lineItems {
        id
        legacyId
      }
    }
  }
}

Arguments (node)

NameTypeDescription
idIDThe unique ID of the object to be returned

Arguments (nodes)

NameTypeDescription
ids[ID]The unique IDs of the objects to be returned

Response (node)

Returns Node

Response (nodes)

Returns [Node]

Error Responses

HTTP ErrorError MessageMeaning
401UnauthorizedYou don’t have access to the endpoint, likely Basic Authentication credentials are missing
401API Token has expiredYou don’t have access to the endpoint, likely that you are either not supplying an API Key, or the key you are supplying is invalid

Further Reading