GraphQL API

This document gives an overview of GraphQL API.

The commercetools platform provides a GraphQL API.

Supported entities

It currently supports following entities:

APIClients (queries and mutation)
CartDiscount (queries and mutation)
Carts and My Carts (queries and mutations)
Category, including category search and auto-complete (queries and mutations)
Channel (queries and mutation)
Customer and My Customer Profile (queries and mutations)
CustomerGroup (queries and mutations)
CustomObject (queries and mutations)
DiscountCode (queries and mutations)
Extension (queries and mutations)
Inventory (queries and mutations)
Message (queries)
Orders and My Orders (queries and mutations)
OrderEdit (queries and mutations)
Payment (queries and mutations)
ProductDiscount (queries and mutations)
ProductType (queries and mutations)
Product (queries and mutations)
Project (queries and mutations) and project-specific Limits (queries)
Reviews (queries and mutations)
ShippingMethod (queries and mutations)
ShoppingList and My Shopping List (queries and mutations)
State (queries and mutations)
Store (queries and mutations)
Subscription (queries and mutations)
TaxCategory (queries and mutations)
Type (queries and mutations)
Zone (queries and mutations)

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.

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 QueryComplexityLimitExceeded error code 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.

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.

CustomFieldsCommand

type is deprecated with the following reason: Use typeResId to fetch the resource identifier.

CustomLineItemDraftOutput

taxCategory is deprecated with the following reason: Use taxCategoryResId to fetch the resource identifier.

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.

Initiator

customer is deprecated with the following reason: Use customerRef to fetch the reference.
user is deprecated with the following reason: Use userRef to fetch the reference.

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.

LineItemDraftOutput

distributionChannel is deprecated with the following reason: Use distributionChannelResId to fetch the resource identifier.
supplyChannel is deprecated with the following reason: Use supplyChannelResId to fetch the resource identifier.

NestedAttributeDefinitionType

typeReference is deprecated with the following reason: Use typeRef to fetch the reference.

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

amountAuthorized is deprecated with the following reason: Payment API deprecated fields update
authorizedUntil is deprecated with the following reason: Payment API deprecated fields update
amountPaid is deprecated with the following reason: Payment API deprecated fields update
amountRefunded is deprecated with the following reason: Payment API deprecated fields update
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.

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.