GraphQL API

Application of scopes

The access to resources is granted by the same scopes that are used on the REST API endpoints. We do not document them here in detail, but we give some guideline on how to find the scope best suitable for a use case in general:

For example, the manage_products scope is required for updating a Product with the Mutation.updateProduct service, the view_products scope would not be sufficient for this.

The view_published_products scope can be used by the Query.products service to retrieve data in masterData.current, but not in masterData.staged. The same applies for the Query.productProjectionSearch service that only returns data with this scope when the staged parameter is set to false in such queries.

Query GraphQL

You can access the GraphQL endpoint with following URL:

https://api.{region}.commercetools.com/{projectKey}/graphql

The endpoint accepts HTTP POST requests with following fields in a JSON body:

• query - String
  The string representation of the Source Text of the Document as specified in the Language section of the GraphQL specification.
• variables - Object - Optional
  A JSON object containing key-value pairs in which the keys are the variable names and the values are the variable values.
• operationName - String - Optional
  The name of the operation, in case you defined several of them in the query.

Example query

The following GraphQL query retrieves the id and the version of a Product with a particular sku provided as variable $sku:

query ($sku: String!) {
  product(sku: $sku) {
    id
    version
  }
}

Along with the above query, we have to pass the variables with the API call in which we assign a value to the $sku variable . In this example we look for the Product containing a ProductVariant with sku = "SKU-123" and so we assign this value to our variable in the variables object like shown below:

{
  "sku": "SKU-123"
}

The following cURL command sends a HTTP POST request including our example query and variables to the GraphQL endpoint on our Project my-shop.

$ curl -X POST https://api.{region}.commercetools.com/my-shop/graphql \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ..." \
  -d '{"query": "query ($sku: String!) {product(sku: $sku) {id version}}", "variables": {"sku": "SKU-123"}}'

Product attributes and custom fields

Product attributes and custom fields are project-specific dynamic fields that can be accessed using raw GraphQL fields. Raw GraphQL fields provide the values as raw JSON that you have to parse yourself. Queries for such fields ensure consistency and good performance.

Raw product attributes

Pseudo-example for using raw product attributes:

fragment variantFields on ProductVariant {
  sku
  attributesRaw {
    name
    value
  }
}

Raw custom fields

Pseudo-example for using raw custom fields:

fragment customFields on ProducePrice {
  custom {
    customFieldsRaw {
      name
      value
    }
  }
}

Existence of query results BETA

For use cases in which you only want to check whether at least one result exists that matches your query, we recommend using the Boolean exists field in your query. This will optimize the query and result in a shorter response time.

query {
  products(where: "productType(id="some-uuid")") {
    exists
  }
}

The API returns true in case there is at least one result matching the query condition, but the field value is false in case no matching result could be found.

{
  "data": {
    "products": {
      "exists": true
    }
  }
}

Reference Expansion

The GraphQL API supports Reference Expansion, just like the HTTP API.

By convention, the GraphQL API offers two fields for each expandable reference:

• <fieldName>Ref - Fetches the Reference to the resource only (lower query complexity).
• <fieldName> - Fetches the expanded resource that is referenced (higher query complexity).
  Returns null if the referenced resource is not found.

Expanding a reference in the GraphQL API impacts the performance of the request, and adds to the complexity score. If you don't need the expanded reference for your use case, you should use the <fieldName>Ref to get better performance on your query.

For an example, if you want to obtain the number of child categories for a specific category, as well as identifiers for its ancestors, the following query would work:

{
  category(id: "some-uuid") {
    children {
      id
    }
    ancestors {
      id
    }
  }
}

The total number of child categories will be the size of children array, and the ancestors identifiers are also available from the ancestors. However, the complexity of the example above can be reduced. If you only need the number of child categories, the childCount field is the way to go. Also, in case you only need the identifiers for the ancestors, it's better to use the ancestorsRef field. This is how the less complex query looks like:

{
  category(id: "some-uuid") {
    childCount
    ancestorsRef {
      id
    }
  }
}

Custom Fields BETA

Reference Expansion for Custom Fields of CustomFieldReferenceType and for the CustomFieldSetType of those is supported in public beta.

If, for example, a Customer has a Custom Field that holds a Reference to another Customer, the following query expands the referenced Customer so that we retrieve the email of the referenced Customer in the same query.

query {
  customer(id: "some-uuid") {
    email
    custom {
      customFieldsRaw(includeNames: ["customfield-name"]) {
        referencedResource {
          ... on Customer {
            email
          }
        }
      }
    }
  }
}

Product Attributes BETA

Reference Expansion for Product Attributes are supported in public beta.

You can include referencedResource (for single references) and referencedResourceSet (for sets of references) under attributesRaw for allVariants or masterVariant:

{
  product(id: "{productID}") {
    masterData {
      current {
        allVariants {
          attributesRaw {
            referencedResource {
              ## If a referenced Product exists, return its name, SKUs, and key
              ... on Product {
                masterData {
                  current {
                    slug(locale: "en")
                  }
                }
                skus
                key
              }
              ## If a referenced ProductType exists, return the Attributes names and ProductType name
              ... on ProductTypeDefinition {
                attributeDefinitions {
                  results {
                    name
                  }
                }
                name
              }
            }
            referencedResourceSet {
              ## If a set of referenced Products exists, return their names, SKUs, and keys
              ... on Product {
                masterData {
                  current {
                    slug(locale: "en")
                  }
                }
                skus
                key
              }
              ## If a set of referenced ProductTypes exists, return their Attribute names and ProductType names
              ... on ProductTypeDefinition {
                attributeDefinitions {
                  results {
                    name
                  }
                }
                name
              }
            }
          }
        }
      }
    }
  }
}

Product Search Attributes BETA

Reference Expansion for Product Search Attributes are supported in public beta.

You can include referencedResource (for single references) and referencedResourceSet (for sets of references) under attributesRaw for masterVariant:

{
  productProjectionSearch(staged: true) {
    results {
      masterVariant {
        attributesRaw(
          includeNames: "{includedAttributes}"
          excludeNames: "{excludedAttributes}"
        ) {
          name
          value
          referencedResource {
            id
            ... on Product {
              skus
            }
          }
          referencedResourceSet {
            id
            ... on Product {
              skus
            }
          }
        }
      }
    }
  }
}

Query complexity

You can fetch a lot of useful information in a single HTTP request using GraphQL. This is really helpful to avoid parsing unused fields, and remove the unnecessary network overhead by reducing the number of requests. At the same time, it is important to remember that a single query can potentially generate a lot of database operations. Hence, you cannot assume that the response time for a query increases linear with the number of fields in the query.
The GraphQL schema defines a "cost" per field, which you can take advantage of by analyzing your queries, using following options:

• Inspecting the x-graphql-query-complexity response header and its value.
• Using GraphiQL's Profiling functionality to measure the impact.

To prevent complex queries from having negative impact on the overall performance, we block queries that exceed the complexity limit of 20 000. If the complexity score for your query is equal or higher than the limit, a QueryComplexityLimitExceeded error code will be returned.

Error response format

The general structure of error responses from the GraphQL API is as follows:

{
  "errors": [
    {
      "message": "Some error message",
      "path": ["somePathSegment"],
      "extensions": {
        "code": "SomeErrorCode"
      }
    }
  ]
}

Each element of the errors array has the following fields:

• message - String - detailed description of the error explaining the root cause of the problem and suggesting you how to correct the error.
• path - Array - Optional - list of query fields ordered from the root of the query response up to the field in which the error occurred. (Only present when an error can be associated to a particular field in the query result).
• extensions - Object - dictionary with additional information where applicable.
  • code - String - one of the error codes listed on the Errors page.

In the following example we experience a problem on the query path category -> children:

query {
  category(id: "650fdb2d-93ea-46f9-97f3-a92816b8305e") {
    children {
      key
    }
  }
}

  "errors": [
    {
      "message": "Too many categories would have been loaded. Please use the 'categories' field instead.",
      "path": ["category", "children"],
      "extensions": {
        "code": "InvalidInput"
      }
    }
  ]
}

Interactive GraphQL console

To explore the GraphQL API, you can use an interactive GraphiQL environment which is available as a part of our ImpEx & API Playground.

Below animation demonstrates how you can use this tool for autocompletion and to explore the documentation that is part of the GraphQL schema:

Public beta functionalities BETA

Find below a list of functionality that is currently in beta.

• createdBy on Versioned
• lastModifiedBy on Versioned
• everything related to Extension
• FixedPriceDiscountValueInput on CartDiscount
• MultiBuyLineItemsTarget and MultiBuyCustomLineItemsTarget on CartDiscount
• everything related to MyCart, MyOrder, MyPayment, MyProfile, MyShoppingList
• Order Edits on Order
• NestedTypes on ProductType
• Subrate on TaxCategory
• exist
• referencedResource and referencedResourceSet
• everything related to ProduceSelection and ProductVariantSelection
• everything related to Quote, QuoteRequest, and StagedQuote
• everything related to DirectDiscount