Documentation Center

List commerce categories and products

Use the externalItems GraphQL query get a list of Magento Commerce categories and products.

Query syntax

The following code illustrates required format for the GraphQL request, followed by a description of the input values:

{
   externalItems([namespace: "NAMESPACE"]
            filter: {
              [context: {
                [namespace: "NAMESPACE",]
                id: "IDENTIFIER",
                type: "TYPE"
              },]
              [type: "TYPE"]
            },
            # Pagination
            [first: NUM_ITEMS,]
            [after: "[cursor]"]
   ) {
     edges {
        node {
            ... on TYPE {
            RESPONSE_FIELD_1
            RESPONSE_FIELD_2
            RESPONSE_FIELD_n
            }
         }
      }
   }
}

Fields and inputs

namespace
Sets the overall query scope, where NAMESPACE is the namespace name for query.
If used in the context identity, the namespace does not need to be separately specified here.
filter
Defines the values you want to match in the query results, and can include one or more of the following:
context
Limits query results based on the context, that is the location in the structure from where you start the query.
namespace
Where NAMESPACE is the namespace where the external data is made available.
If defined at a higher level of the query, the namespace does not need to be separately specified here.
id
Where IDENTIFIER is the unique identifier provided by the external system.
type
Where TYPE refers to the external entity type.
type
Limits query results to entities with the same entity type
# Pagination
The following two parameters work together for data pagination:
first
The value for NUM_ITEMS sets the first number of matching items to retrieve.
For example, a value of "100" would return the first 100 items.
after
For all requests following the initial one, the value for CURSOR defines the starting point of the query.
Typically, in each subsequent request, you would set the value to whatever was returned as the "cursor" position of the last item returned in the preceding request.
edges
A generic GraphQL term for the connections between nodes, which the externalItems query traverses to get to individual nodes.
node
Contains the response definition for the entity.
... on TYPE
Defines the query response, where:
  • TYPE is the entity type and matches the TYPE value in the identity section.
  • RESPONSE_FIELD_1 to RESPONSE_FIELD_n are the specific data fields that you want to be returned in the response.
The GraphQL type definition of the entity type determines which fields are available in a response.

Example request and response

The first sample code block illustrates a request to retrieve all the products under a specified category. The second code block illustrates the corresponding response with the requested data for each Magento Commerce product.

RequestResponse
{ externalItems(namespace:
  "magento", 
  filter: { 
    context: 
    { id: "MTU%3d_Y2F0ZWdvcnk%3d" type: "MagentoCategory" } 
  }, first: 10, after: "Ng==")
  { edges {
    cursor node {
      identity { id type } ...
      on ExternalContent { title }    }   
  }     
  }
}












































{
  "data": {
    "externalItems": {
      "edges": [
        {
          "cursor": "Nw==",
          "node": {
            "identity": {
              "id": "Mzg%3d_Y2F0ZWdvcnk%3d",
              "type": "MagentoCategory"
            },
            "title": "What's New"
          }
        },
        {
          "cursor": "MTE=",
          "node": {
            "identity": {
              "id": "Nw%3d%3d_Y2F0ZWdvcnk%3d",
              "type": "MagentoCategory"
            },
            "title": "Collections"
          }
        },
        {
          "cursor": "MTM=",
          "node": {
            "identity": {
              "id": "Mjk%3d_Y2F0ZWdvcnk%3d",
              "type": "MagentoCategory"
            },
            "title": "Promotions"
          }
        },
        {
          "cursor": "MTQ=",
          "node": {
            "identity": {
              "id": "Mzc%3d_Y2F0ZWdvcnk%3d",
              "type": "MagentoCategory"
            },
            "title": "Sale"
          }
        },
        {
          "cursor": "MTY=",
          "node": {
            "identity": {
              "id": "NDI%3d_Y2F0ZWdvcnk%3d",
              "type": "MagentoCategory"
            },
            "title": "Office Supplies"
          }
        }
      ]
    }
  }
}