Queries

Queries read data from StoreOS without changing anything. All queries need x-tenant. Only me and myOrders need a customer JWT.

Catalog — products & collections

What catalog queries do: Load products (items for sale) and collections (grouped products) for shop and product pages.

products

What it does: Returns a paginated list of published products. Supports search and collection filters.

Use when: Shop listing, search results, homepage grids.

query Products($input: ProductListInput) {
  products(input: $input) {
    nodes {
      _id handle title price comparingPrice status
      variants { variantId isInStock attributes }
    }
    meta { totalCount currentPage hasNextPage totalPages }
  }
}

REST equivalent: GET /api/v1/products · SDK: getProducts()

productByHandle · productById

What they do: Return one product with full detail — descriptions, images, variants, price.

query ProductByHandle($handle: String!) {
  productByHandle(handle: $handle) {
    _id handle title shortDescription longDescription price
    variants { variantId isInStock attributes }
    gallery { key provider external }
    thumbnail { key provider external }
  }
}

REST equivalent: GET /api/v1/products/handle/:handle · SDK: getProduct({ handle })

collections · collection

What they do: List or fetch collections — named groups like "Best sellers" or "Electronics".

Use when: Navigation, homepage sections, filtering products by collection.

query Collections($input: CollectionListInput) {
  collections(input: $input) {
    nodes { _id name }
    meta { totalCount }
  }
}

REST equivalent: GET /api/v1/collections · SDK: getCollections()

Store config — storeFront

What it does: Returns your store's settings — not products, but rules and content for the whole site.

query StoreFront {
  storeFront {
    name businessPhoneNumber
    customerSupportInfo { email phoneNumber }
    charges {
      deliveryInsideCapitalCharge
      deliveryOutsideCapitalCharge
      taxRate
    }
    legalPolicies {
      privacyPolicy refundPolicy termsAndConditions
    }
  }
}

REST equivalent: GET /api/v1/tenant · SDK: getTenant()

Orders — read

myOrders

What it does: Order history for the logged-in customer — paginated list with status and totals.

Auth: Bearer JWT required.

Use when: Customer dashboard, "My orders" page.

query MyOrders($input: MyOrdersInput) {
  myOrders(input: $input) {
    nodes {
      invoiceUID invoiceStatus paymentStatus netTotalAmount createdAt
    }
    meta { totalCount }
  }
}

REST equivalent: GET /api/v1/orders · SDK: getMyOrders()

orderDetailsById

What it does: One order by invoice UID — line items, shipping address, payment status.

Auth: Not required — use for public order tracking when the customer has the order ID.

query OrderDetails($orderId: String!) {
  orderDetailsById(orderId: $orderId) {
    invoiceUID invoiceStatus paymentStatus
    lineItems { name quantity unitPrice }
    shippingAddress { caption latitude longitude }
  }
}

REST equivalent: GET /api/v1/orders/:orderId · SDK: getOrder(orderId)

Product enums

Images

Products use gallery and thumbnail with key, provider, external. Build URLs with https://cdn.storeos.dev + key.