GraphQL API

This document gives an overview of GraphQL API.

The commercetools platform provides a GraphQL API.

Supported entities

It currently supports following entities:

Query GraphQL

You can access the GraphQL endpoint with following URL:

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

It accepts POST requests with following fields in a JSON body:

  • query - String - GraphQL query as a string
  • variables - Object - Optional - containing JSON object that defines variables for your query
  • operationName - String - Optional - the name of the operation, in case you defined several of them in the query

Here is an example of a GraphQL query:

$ curl -X POST https://api.{region}.{cloudProvider}.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"}}'

Interactive GraphQL console

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

Here is a short demonstration if the GraphiQL tool and how you can use it to discover the schema:

GraphiQL demonstration

Product attributes and custom fields

Product attributes and custom fields are dynamic fields, customized for the needs of each project.

To access them, you can use raw GraphQL fields.

Raw product attributes and raw custom fields

Raw GraphQL fields provide the values as raw json that you have to parse yourself, but they are always consistent, and they are performing well.

Pseudo-example how to use raw product attributes:

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

Pseudo-example how to use raw custom fields:

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

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. Our schema defines a “cost” per field, which you can take advantage of by analyzing your queries, using one of the two possibilities:

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

To prevent overly complex queries from having negative impact on the platform, we block queries that exceed the complexity limit of 20000. If the complexity score for your query is equal or higher than the limit, a Query is too complex/expensive error will be returned.

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.
  • <fieldName> - Fetches the expanded resource that is referenced.
    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
    }
  }
}

GraphQL General Availability

As part of our initiative to move GraphQl out of beta, and make it generally available, we are removing some functionality.

Deprecated fields

The following list contains deprecated fields available via GraphQL API which will be removed at some point. We encourage you to update your code and use the suggested alternatives at your earliest convenience.

Asset

  • customFieldsRaw is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFields is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFieldList is deprecated with the following reason: Typed custom fields are no longer supported, please use customFieldsRaw instead.

Cart

  • customFieldsRaw is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFields is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFieldList is deprecated with the following reason: Typed custom fields are no longer supported, please use customFieldsRaw instead.

CartDiscount

  • customFieldsRaw is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFields is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFieldList is deprecated with the following reason: Typed custom fields are no longer supported, please use customFieldsRaw instead.

Category

  • productCount is deprecated with the following reason: The returned number is representing only staged products. Use tagedProductCount instead.
  • customFieldsRaw is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFields is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFieldList is deprecated with the following reason: Typed custom fields are no longer supported, please use customFieldsRaw instead.

CategorySearch

  • productCount is deprecated with the following reason: The returned number is representing only staged products. Use stagedProductCount instead.
  • customFieldsRaw is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFields is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFieldList is deprecated with the following reason: Typed custom fields are no longer supported, please use customFieldsRaw instead.

Channel

  • typeId is deprecated with the following reason: Use channelRef to fetch the reference.
  • customFieldsRaw is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFields is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFieldList is deprecated with the following reason: Typed custom fields are no longer supported, please use customFieldsRaw instead.

CustomFieldsType

  • customFields is deprecated with the following reason: Typed custom fields are no longer supported, please use customFieldsRaw instead.

CustomLineItem

  • customFieldsRaw is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFields is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFieldList is deprecated with the following reason: Typed custom fields are no longer supported, please use customFieldsRaw instead.

Customer

  • customFieldsRaw is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFields is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFieldList is deprecated with the following reason: Typed custom fields are no longer supported, please use customFieldsRaw instead.

CustomerGroup

  • typeId is deprecated with the following reason: Use customerGroupRef to fetch the reference.
  • customFieldsRaw is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFields is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFieldList is deprecated with the following reason: Typed custom fields are no longer supported, please use customFieldsRaw instead.

DiscountCode

  • customFieldsRaw is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFields is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFieldList is deprecated with the following reason: Typed custom fields are no longer supported, please use customFieldsRaw instead.

DiscountedProductPriceValue

  • discountRel is deprecated with the following reason: Will be removed in the future. Please use discount.

InventoryEntry

  • customFieldsRaw is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFields is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFieldList is deprecated with the following reason: Typed custom fields are no longer supported, please use customFieldsRaw instead.

LineItem

  • customFieldsRaw is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFields is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFieldList is deprecated with the following reason: Typed custom fields are no longer supported, please use customFieldsRaw instead.

Order

  • customFieldsRaw is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFields is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFieldList is deprecated with the following reason: Typed custom fields are no longer supported, please use customFieldsRaw instead.

Payment

Product

  • catalogData is deprecated with the following reason: Only masterData supported.

ProductPrice

  • customFieldsRaw is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFields is deprecated with the following reason: Please use custom.customFieldsRaw.
  • customFieldList is deprecated with the following reason: Typed custom fields are no longer supported, please use customFieldsRaw instead.

ProductVariant

  • attributes is deprecated with the following reason: Typed attributes are no longer supported, please use attributesRaw instead.
  • attributeList is deprecated with the following reason: Typed attributes are no longer supported, please use attributesRaw instead.

ShippingMethod

  • description is deprecated with the following reason: Use localizedDescription.

TaxCategory

  • typeId is deprecated with the following reason: Use taxCategoryRef to fetch the reference.

Deprecated scopes

The following list contains deprecated scopes available via GraphQL API which will be removed at some point. We encourage you to update your code and use the suggested alternatives at your earliest convenience.

DiscountCode

  • Retrieving: view_orders:{projectKey} is deprecated, please use view_discount_codes:{projectKey} instead.
  • Mutating: manage_orders:{projectKey} is deprecated, please use manage_discount_codes:{projectKey} instead.

State

  • Retrieving: view_orders:{projectKey} is deprecated, please use view_states:{projectKey} instead.
  • Mutating: manage_orders:{projectKey} is deprecated, please use manage_states:{projectKey} instead.

Cart

  • Replicate a Cart: manage_project:{projectKey} is deprecated, please use manage_orders:{projectKey} instead.

Category

  • Retrieving: view_products:{projectKey} is deprecated, please use view_categories:{projectKey} instead.
  • Mutating: manage_products:{projectKey} is deprecated, please use manage_categories:{projectKey} instead.

CustomerGroup

  • Retrieving: view_customers:{projectKey} is deprecated, please use view_customer_groups:{projectKey} instead.
  • Mutating: manage_customers:{projectKey} is deprecated, please use manage_customer_groups:{projectKey} instead.

CartDiscount

  • Retrieving: view_orders:{projectKey} is deprecated, please use view_cart_discounts:{projectKey} instead.
  • Mutating: manage_orders:{projectKey} is deprecated, please use manage_cart_discounts:{projectKey} instead.

State

  • Retrieving: view_orders:{projectKey} is deprecated, please use view_states:{projectKey} instead.
  • Mutating: manage_orders:{projectKey} is deprecated, please use manage_states:{projectKey} instead.

TaxCategory

  • Retrieving: view_products:{projectKey} is deprecated, please use view_tax_categories:{projectKey} instead.
  • Mutating: manage_products:{projectKey} is deprecated, please use manage_tax_categories:{projectKey} instead.

ShippingMethod

  • Retrieving: view_orders:{projectKey} is deprecated, please use view_shipping_methods:{projectKey} instead.
  • Mutating: manage_orders:{projectKey} is deprecated, please use manage_shipping_methods:{projectKey} instead.