GraphQL basics

Thor Commerce exposes separate Admin and Storefront schemas, but both use the same GraphQL fundamentals: named operations, typed variables, selection sets, cursor connections, fragments, and structured errors.

Use the Admin API to configure and operate a project. Use the Storefront API for buyer-facing catalog, cart, checkout, and customer experiences. The fields and authorization rules differ, while the way you compose and process an operation stays the same.

Send GraphQL over HTTP as JSON with a query string and, when needed, a variables object. Use the project-specific endpoint and authentication described on each API’s introduction page.

Operations and selection sets

Every request starts with an operation type—usually query for reads or mutation for writes—and should have a descriptive operation name. The selection set inside braces states exactly which fields the response should contain.

  • Select only the fields the caller needs. Adding a field can cause additional resolver and data-source work.
  • Name operations so traces and error reports identify them, such as ProductGrid or CreateCart.
  • Use aliases when the same field must be requested with different arguments in one operation.
  • GraphQL field names are case-sensitive and are validated against the selected API schema before execution.

Variables and input objects

Declare external values as variables and send them separately from the operation. Do not construct an operation by interpolating customer input, search text, IDs, or credentials into the GraphQL source.

Variables are validated against their declared types. A mutation commonly accepts one required input object, which keeps related values together and lets the schema evolve without adding many top-level arguments.

In $input: CartCreateInput!, the trailing ! means the variable cannot be null. The input object’s own field definitions determine which nested values are required.

JSON has no enum or ID types. Send enum values and IDs as JSON strings; GraphQL validates those strings against the variable’s declared type.

Nullability and lists

Read a type from the inside out:

TypeMeaning
ProductThe object can be null.
Product!The object cannot be null.
[Product]The list and its items can be null.
[Product!]!The list is present and every item is present.

A nullable field is not necessarily an error. A value can be absent because it does not apply, has not been configured, is not visible in the current context, or failed during partial execution. Let generated types preserve the schema’s nullability instead of forcing every field to be present.

Connections and pagination

List operations generally return a connection rather than a raw array. Use nodes when you only need records, or edges { cursor node } when each item’s cursor is useful. Request pageInfo and pass endCursor to after for the next page.

Cursors are opaque positions in an ordered result. Do not decode them, and keep filters, sorting, and Storefront commerce context unchanged between pages. See Pagination for forward and backward traversal.

Fragments, interfaces, and unions

Fragments keep repeated selections consistent. Inline fragments select fields that only exist on a concrete implementation of an interface or member of a union. Request __typename when the application must distinguish the returned type.

Fragments do not make a separate network request. They are composed into the operation sent to the API.

Process every error channel

HTTP status, the response’s top-level errors array, and mutation payload errors answer different questions:

  1. The HTTP response reports whether the request reached and was accepted by the GraphQL service.
  2. Top-level GraphQL errors report parsing, validation, authorization, or field execution failures. A response can contain both partial data and errors.
  3. Many mutations expose typed business errors in their payload. A 200 OK response can therefore still represent a rejected business operation.

Always inspect the error channels requested by the operation before treating it as successful. Storefront retry and user-interface guidance is covered in Error handling.

Thor-specific conventions