GraphQL API

The commercetools platform provides a GraphQL API. It currently supports following entities:

• APIClients (queries and mutation)
• CartDiscount (queries and mutation)
• Carts and MyCarts (queries and mutations)
• Category, including category search and auto-complete (queries and mutations)
• Channel (queries only)
• Customer and My Customer Profile (queries and mutations)
• CustomerGroup (queries only)
• DiscountCode (queries and mutations)
• Inventory (queries and mutations)
• Orders and MyOrders (queries and mutations)
• Payment (queries only)
• ProductDiscount (queries only)
• ProductType (queries and mutations)
• Product (queries and mutations)
• Project (queries and mutations)
• ShippingMethod (queries and mutations)
• State (queries only)
• Store (queries and mutations)
• TaxCategory (queries and mutations)
• Type (queries only)
• Zone (queries and mutations)

You can access the GraphQL endpoint with following URL:

https://api.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.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 as well as custom fields are dynamically generated for project’s GraphQL schema, depending on your ProductType and Type definitions, in an eventually consistent fashion.

In order 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:

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 - Reference
• <fieldName> - Optional
  The expanded resource.
  Returns null if the referenced resource is not found.

Expanding a reference in the GraphQL API impacts the performance of the request. You can use the GraphiQL’s Profiling function to measure the impact for your project: