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
- CartDiscount
- Carts and My Carts
- Category, including category search and auto-complete
- Channel
- Customer and My Customer Profile
- CustomerGroup
- CustomObject
- DiscountCode
- Extension
- Inventory
- Message (supported for queries)
- Orders and My Orders
- OrderEdit
- Payment
- ProductDiscount
- ProductSuggestion
- ProductType
- Product
- Project and project-specific Limits (supported for queries)
- Reviews
- ShippingMethod
- ShoppingList and My Shopping List
- State
- Store
- Subscription
- TaxCategory
- Type
- Zone
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 stringvariables
- Object - Optional - containing JSON object that defines variables for your queryoperationName
- 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:
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 {skuattributesRaw {namevalue}}
Pseudo-example how to use raw custom fields:
fragment customFields on ProducePrice {custom {customFieldsRaw {namevalue}}}
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.
Returnsnull
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") {childCountancestorsRef {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 on 31 January 2021. 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 usecustom.customFieldsRaw
.customFields
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFieldList
is deprecated with the following reason: Typed custom fields are no longer supported, please usecustomFieldsRaw
instead.
Cart
customFieldsRaw
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFields
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFieldList
is deprecated with the following reason: Typed custom fields are no longer supported, please usecustomFieldsRaw
instead.
CartDiscount
customFieldsRaw
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFields
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFieldList
is deprecated with the following reason: Typed custom fields are no longer supported, please usecustomFieldsRaw
instead.
Category
productCount
is deprecated with the following reason: The returned number is representing only staged products. UsestagedProductCount
instead.customFieldsRaw
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFields
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFieldList
is deprecated with the following reason: Typed custom fields are no longer supported, please usecustomFieldsRaw
instead.
CategorySearch
productCount
is deprecated with the following reason: The returned number is representing only staged products. UsestagedProductCount
instead.customFieldsRaw
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFields
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFieldList
is deprecated with the following reason: Typed custom fields are no longer supported, please usecustomFieldsRaw
instead.
Channel
typeId
is deprecated with the following reason: UsechannelRef
to fetch the reference.customFieldsRaw
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFields
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFieldList
is deprecated with the following reason: Typed custom fields are no longer supported, please usecustomFieldsRaw
instead.
CustomFieldsType
customFields
is deprecated with the following reason: Typed custom fields are no longer supported, please usecustomFieldsRaw
instead.
CustomLineItem
customFieldsRaw
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFields
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFieldList
is deprecated with the following reason: Typed custom fields are no longer supported, please usecustomFieldsRaw
instead.
Customer
customFieldsRaw
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFields
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFieldList
is deprecated with the following reason: Typed custom fields are no longer supported, please usecustomFieldsRaw
instead.
CustomerGroup
typeId
is deprecated with the following reason: UsecustomerGroupRef
to fetch the reference.customFieldsRaw
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFields
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFieldList
is deprecated with the following reason: Typed custom fields are no longer supported, please usecustomFieldsRaw
instead.
CustomFieldsCommand
type
is deprecated with the following reason: UsetypeResId
to fetch the resource identifier.
CustomLineItemDraftOutput
taxCategory
is deprecated with the following reason: UsetaxCategoryResId
to fetch the resource identifier.
DiscountCode
customFieldsRaw
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFields
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFieldList
is deprecated with the following reason: Typed custom fields are no longer supported, please usecustomFieldsRaw
instead.
DiscountedProductPriceValue
discountRel
is deprecated with the following reason: Will be removed in the future. Please usediscount
.
Initiator
customer
is deprecated with the following reason: UsecustomerRef
to fetch the reference.user
is deprecated with the following reason: UseuserRef
to fetch the reference.
InventoryEntry
customFieldsRaw
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFields
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFieldList
is deprecated with the following reason: Typed custom fields are no longer supported, please usecustomFieldsRaw
instead.
LineItem
customFieldsRaw
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFields
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFieldList
is deprecated with the following reason: Typed custom fields are no longer supported, please usecustomFieldsRaw
instead.
LineItemDraftOutput
distributionChannel
is deprecated with the following reason: UsedistributionChannelResId
to fetch the resource identifier.supplyChannel
is deprecated with the following reason: UsesupplyChannelResId
to fetch the resource identifier.
NestedAttributeDefinitionType
typeReference
is deprecated with the following reason: UsetypeRef
to fetch the reference.
Order
customFieldsRaw
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFields
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFieldList
is deprecated with the following reason: Typed custom fields are no longer supported, please usecustomFieldsRaw
instead.
Payment
amountAuthorized
is deprecated with the following reason: Payment API deprecated fields updateauthorizedUntil
is deprecated with the following reason: Payment API deprecated fields updateamountPaid
is deprecated with the following reason: Payment API deprecated fields updateamountRefunded
is deprecated with the following reason: Payment API deprecated fields updatecustomFieldsRaw
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFields
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFieldList
is deprecated with the following reason: Typed custom fields are no longer supported, please usecustomFieldsRaw
instead.
Product
catalogData
is deprecated with the following reason: OnlymasterData
supported.
ProductPrice
customFieldsRaw
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFields
is deprecated with the following reason: Please usecustom.customFieldsRaw
.customFieldList
is deprecated with the following reason: Typed custom fields are no longer supported, please usecustomFieldsRaw
instead.
ProductVariant
attributes
is deprecated with the following reason: Typed attributes are no longer supported, please useattributesRaw
instead.attributeList
is deprecated with the following reason: Typed attributes are no longer supported, please useattributesRaw
instead.
ShippingMethod
description
is deprecated with the following reason: UselocalizedDescription
.
TaxCategory
typeId
is deprecated with the following reason: UsetaxCategoryRef
to fetch the reference.
Deprecated scopes
The following list contains deprecated scopes available via GraphQL API which will be removed on 31 January 2021. We encourage you to update your code and use the suggested alternatives at your earliest convenience.
DiscountCode
- Retrieving:
view_orders:{projectKey}
is deprecated, please useview_discount_codes:{projectKey}
instead. - Mutating:
manage_orders:{projectKey}
is deprecated, please usemanage_discount_codes:{projectKey}
instead.
State
- Retrieving:
view_orders:{projectKey}
is deprecated, please useview_states:{projectKey}
instead. - Mutating:
manage_orders:{projectKey}
is deprecated, please usemanage_states:{projectKey}
instead.
Cart
- Replicate a Cart:
manage_project:{projectKey}
is deprecated, please usemanage_orders:{projectKey}
instead.
Category
- Retrieving:
view_products:{projectKey}
is deprecated, please useview_categories:{projectKey}
instead. - Mutating:
manage_products:{projectKey}
is deprecated, please usemanage_categories:{projectKey}
instead.
CustomerGroup
- Retrieving:
view_customers:{projectKey}
is deprecated, please useview_customer_groups:{projectKey}
instead. - Mutating:
manage_customers:{projectKey}
is deprecated, please usemanage_customer_groups:{projectKey}
instead.
CartDiscount
- Retrieving:
view_orders:{projectKey}
is deprecated, please useview_cart_discounts:{projectKey}
instead. - Mutating:
manage_orders:{projectKey}
is deprecated, please usemanage_cart_discounts:{projectKey}
instead.
State
- Retrieving:
view_orders:{projectKey}
is deprecated, please useview_states:{projectKey}
instead. - Mutating:
manage_orders:{projectKey}
is deprecated, please usemanage_states:{projectKey}
instead.
TaxCategory
- Retrieving:
view_products:{projectKey}
is deprecated, please useview_tax_categories:{projectKey}
instead. - Mutating:
manage_products:{projectKey}
is deprecated, please usemanage_tax_categories:{projectKey}
instead.
ShippingMethod
- Retrieving:
view_orders:{projectKey}
is deprecated, please useview_shipping_methods:{projectKey}
instead. - Mutating:
manage_orders:{projectKey}
is deprecated, please usemanage_shipping_methods:{projectKey}
instead.
CustomObject
- Retrieving:
view_products:{projectKey}
is deprecated, please useview_key_value_documents:{projectKey}
instead. - Mutating:
manage_products:{projectKey}
is deprecated, please usemanage_key_value_documents:{projectKey}
instead.