Skip to main content
The JTL GraphQL schema follows consistent naming, response, and pagination patterns. Once you understand these conventions, you can explore the Schema Reference and build queries directly from the available types and fields. This guide walks through the conventions you’ll see across the GraphQL API. For authentication, request headers, and reusable client configuration, see Using Platform APIs.

​
Operation Naming

Query and mutation root fields use PascalCase with a verb prefix that describes what the operation does. Most operations follow these naming patterns:
OperationPatternExample
List a resourceQuery<Entity>QueryItems, QueryCompanies
Fetch one by IDGet<Entity>ByIdGetSalesOrderById, GetItemById
Create a resourceCreate<Entity>CreateCategory, CreateItem
Modify a resourceUpdate<Entity>, Change<Entity>UpdateCategory, ChangeItem
Verbs extend beyond these four where an operation does something more specific. Items are modified with ChangeItem rather than UpdateItem, suppliers are attached with AddItemSupplier, and operations like CalculateSalesOrder, ReleaseProductionOrder, and ListTaxClassesWithTaxRates name the action they perform. Treat the table as the shape to expect, and check the Schema Reference for the exact verb on any specific operation. A query that lists items begins at the QueryItems root field: 
query GetItems {
  QueryItems(first: 10) {
    nodes {
      id
      sku
      name
    }
    totalCount
  }
}

​
Selection Sets

Every field that returns an object requires a selection set: the nested fields you want back from it. A field that returns a scalar (a string, number, boolean, or ID) can be queried directly and requires no further nesting. If a field returns an object, you must specify which fields you want from that object. QueryItems returns a list object, so the query expands into nodes, and each node expands into the fields you want returned: 
query GetItems {
  QueryItems(first: 10) {
    nodes {
      id
      name
    }
    totalCount
  }
}
GraphQL lets you request only the fields you need. Listing fewer fields returns a smaller payload; listing more returns more detail in the same request. The operation string is the only thing that changes.

​
List Responses

List queries return a connection object with a consistent shape across every resource.
FieldTypeDescription
nodesarrayThe records on the current page
pageInfoobjectPagination metadata, including hasNextPage and endCursor
totalCountintegerTotal number of matching records across all pages
The actual records are returned in the nodes array: 
query GetItems {
  QueryItems(first: 20) {
    nodes {
      id
      sku
      name
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

​
Pagination

To fetch large result sets, list queries use cursor-based pagination. You control pagination through query arguments and use the values returned in pageInfo to request the next or previous page. Pass first to control how many records are returned. The first request typically omits after. To fetch the next page, take the value of pageInfo.endCursor from the previous response and pass it as the after argument. Repeat this process until pageInfo.hasNextPage is false. To page backward, use last and before instead, and use pageInfo.startCursor and pageInfo.hasPreviousPage to navigate earlier pages. 
query GetItems($first: Int, $after: String) {
  QueryItems(first: $first, after: $after) {
    nodes {
      id
      name
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
For the full pagination loop with code samples, see Pagination.

​
Arguments

Operations accept arguments for paging, sorting, and filtering, supplied as GraphQL variables. Most list queries accept the same paging, sorting, and filtering arguments:
ArgumentPurpose
firstPage size when paging forward
afterCursor marking where the next page begins
lastPage size when paging backward
beforeCursor marking where the previous page ends
orderSort order, as an array of { field: ASC | DESC } objects
whereFilter conditions, using a structured input type
Some queries take additional arguments of their own. QueryItems and QueryCustomers, for example, also accept searchTerm, searchOperator, and searchField for text search. The reference lists the full argument set on each operation. Sort with order and filter with where: 
query GetItems($first: Int, $order: [ItemListItemSortInput!], $where: ItemListItemFilterInput) {
  QueryItems(first: $first, order: $order, where: $where) {
    nodes {
      id
      name
    }
    totalCount
  }
}

{
  "first": 20,
  "order": [{ "name": "ASC" }],
  "where": { "name": { "contains": "T-shirt" } }
}
The operators available in a where filter depend on the field type. String fields typically support operators such as eq, neq, contains, startsWith, and in. Numeric and date fields typically support comparison operators such as eq, gt, gte, lt, lte, and in. Each field uses a filter type that defines which operators are available. For example, string fields use StringOperationFilterInput. Refer to the Schema Reference to see the operators supported by a specific field.

​
Input Types

Mutations take their data as a single structured input object rather than loose arguments. Input type names follow the operation they belong to and end in Input, such as CreateCategoryCommandRequestInput. A mutation declares the input as a variable, then passes it through: 
mutation CreateCategory($request: CreateCategoryCommandRequestInput) {
  CreateCategory(request: $request) {
    categoryId
  }
}

{
  "request": {
    "name": "Summer Collection",
    "sortNumber": 1,
    "parentId": null
  }
}
The reference lists every field on an input type, which fields are required, and their types. Structure your variables object to match the input type definition shown in the schema.

​
Reading the Schema Reference

The schema reference is generated from the live API, so the types and fields you see there reflect the conventions described above. When you open a type in the Schema Reference, apply these conventions to read it:
  • Root fields under Query are the entry points for reads; root fields under Mutation are the entry points for writes. Their names follow the patterns in Operation Naming.
  • A field’s type tells you whether you can request it directly or need to select additional fields from it. Scalar types (String, Int, Boolean, ID, and enums) can be requested directly. Object types require a selection set.
  • List queries return a connection type carrying nodes, pageInfo, and totalCount.
  • A field marked with ! is non-null. On an input type, a non-null field is required in your variables.
  • Arguments and input fields appear alongside each operation, with their own types and required markers. The GraphQL Playground supports autocomplete and inline schema docs, so you can confirm field names and types as you build a query.

​
What’s Next

Using Platform APIs

Wire GraphQL into your backend with headers, authentication, and a reusable client.

GraphQL Playground

Explore the schema interactively with autocomplete and inline docs.

Pagination

The full cursor-based pagination pattern with code samples.

Error Handling

Error formats, the errors array, and retry strategies.