Queries Reference

All available GraphQL queries for fetching data from Unified Commerce Platform.

Overview

Queries are read-only operations used to fetch data. Unlike REST APIs with multiple endpoints, GraphQL uses a single endpoint where you specify exactly what data you need.

Query Structure

query QueryName($variable: Type!) {
  queryField(argument: $variable) {
    field1
    field2
    nestedObject {
      nestedField
    }
  }
}

Product Catalog

product

Fetch a single product by ID or SKU.

query GetProduct($id: ID!) {
  product(id: $id) {
    id
    name
    description
    price
    currency
    sku
    status
    images {
      url
      alt
      order
    }
    categories {
      id
      name
      slug
    }
    variants {
      id
      sku
      price
      options {
        name
        value
      }
    }
    inventory {
      available
      reserved
    }
  }
}

Arguments:

*Either id or sku must be provided.

Returns: Product or null if not found

products

Fetch a list of products with filtering and pagination.

query GetProducts(
  $first: Int!
  $after: String
  $filters: ProductFilters
  $sortBy: ProductSortField
  $sortOrder: SortOrder
) {
  products(
    first: $first
    after: $after
    filters: $filters
    sortBy: $sortBy
    sortOrder: $sortOrder
  ) {
    edges {
      cursor
      node {
        id
        name
        price
        currency
        images(limit: 1) {
          url
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Arguments:

ProductFilters:

input ProductFilters {
  categoryId: ID
  categorySlug: String
  searchQuery: String
  priceMin: Money
  priceMax: Money
  inStock: Boolean
  status: ProductStatus
  featured: Boolean
  tags: [String!]
}

Returns: ProductConnection

category

Fetch a single category by ID or slug.

query GetCategory($id: ID, $slug: String) {
  category(id: $id, slug: $slug) {
    id
    name
    slug
    description
    image {
      url
      alt
    }
    parent {
      id
      name
    }
    children {
      id
      name
      slug
    }
    products(first: 20) {
      edges {
        node {
          id
          name
          price
        }
      }
    }
  }
}

Arguments:

*Either id or slug must be provided.

Returns: Category or null

categories

Fetch all categories in a hierarchical structure.

query GetCategories($parentId: ID) {
  categories(parentId: $parentId) {
    id
    name
    slug
    image {
      url
    }
    productCount
    children {
      id
      name
      slug
    }
  }
}

Arguments:

Returns: [Category!]!

Orders

order

Fetch a single order by ID or order number.

query GetOrder($id: ID, $orderNumber: String) {
  order(id: $id, orderNumber: $orderNumber) {
    id
    orderNumber
    status
    total
    subtotal
    tax
    shipping
    currency
    createdAt
    updatedAt

    items {
      id
      product {
        id
        name
        images(limit: 1) {
          url
        }
      }
      quantity
      price
      subtotal
    }

    customer {
      id
      name
      email
    }

    shippingAddress {
      line1
      line2
      city
      state
      postalCode
      country
    }

    payment {
      id
      status
      method
      amount
    }

    fulfillment {
      status
      trackingNumber
      carrier
      shippedAt
      deliveredAt
    }
  }
}

Arguments:

*Either id or orderNumber must be provided.

Returns: Order or null

orders

Fetch a list of orders with filtering.

query GetOrders(
  $first: Int!
  $after: String
  $filters: OrderFilters
  $sortBy: OrderSortField
  $sortOrder: SortOrder
) {
  orders(
    first: $first
    after: $after
    filters: $filters
    sortBy: $sortBy
    sortOrder: $sortOrder
  ) {
    edges {
      cursor
      node {
        id
        orderNumber
        status
        total
        currency
        createdAt
        customer {
          name
          email
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

OrderFilters:

input OrderFilters {
  customerId: ID
  status: OrderStatus
  startDate: DateTime
  endDate: DateTime
  minTotal: Money
  maxTotal: Money
}

Returns: OrderConnection

Customers (CRM)

customer

Fetch a single customer by ID or email.

query GetCustomer($id: ID, $email: EmailAddress) {
  customer(id: $id, email: $email) {
    id
    name
    email
    phone
    createdAt

    # Purchase history
    totalSpent
    orderCount
    averageOrderValue
    lastOrderDate

    # Loyalty
    loyaltyPoints
    loyaltyTier

    # Addresses
    addresses {
      id
      line1
      city
      state
      postalCode
      country
      isDefault
    }

    # Recent orders
    orders(first: 10) {
      edges {
        node {
          id
          orderNumber
          total
          createdAt
        }
      }
    }
  }
}

Arguments:

*Either id or email must be provided.

Returns: Customer or null

customers

Fetch a list of customers.

query GetCustomers(
  $first: Int!
  $after: String
  $searchQuery: String
  $filters: CustomerFilters
) {
  customers(
    first: $first
    after: $after
    searchQuery: $searchQuery
    filters: $filters
  ) {
    edges {
      cursor
      node {
        id
        name
        email
        phone
        totalSpent
        orderCount
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

CustomerFilters:

input CustomerFilters {
  loyaltyTier: String
  minTotalSpent: Money
  minOrderCount: Int
  createdAfter: DateTime
}

Returns: CustomerConnection

Cart

cart

Fetch the current user's cart or a cart by ID.

query GetCart($id: ID) {
  cart(id: $id) {
    id
    items {
      id
      product {
        id
        name
        price
        images(limit: 1) {
          url
        }
        inventory {
          available
        }
      }
      quantity
      subtotal
    }
    subtotal
    tax
    shipping
    total
    currency
    coupon {
      code
      discountAmount
    }
  }
}

Arguments:

Returns: Cart or null

Inventory

inventory

Fetch inventory levels for a product.

query GetInventory($productId: ID!) {
  inventory(productId: $productId) {
    productId
    available
    reserved
    inTransit
    warehouses {
      id
      name
      location
      available
    }
    lowStockThreshold
    isLowStock
    lastRestockedAt
  }
}

Arguments:

Returns: Inventory or null

Identity

currentUser

Fetch the currently authenticated user.

query GetCurrentUser {
  currentUser {
    id
    email
    name
    phone
    roles {
      id
      name
      permissions
    }
    mfaEnabled
    lastLoginAt
    createdAt
  }
}

No arguments required (uses authentication token)

Returns: User or null

user

Fetch a user by ID (requires admin permission).

query GetUser($id: ID!) {
  user(id: $id) {
    id
    email
    name
    phone
    roles {
      name
      permissions
    }
    status
    createdAt
  }
}

Arguments:

Returns: User or null

Payment

payment

Fetch a payment by ID.

query GetPayment($id: ID!) {
  payment(id: $id) {
    id
    amount
    currency
    status
    method
    last4
    brand
    createdAt

    order {
      id
      orderNumber
    }

    refunds {
      id
      amount
      reason
      createdAt
    }
  }
}

Arguments:

Returns: Payment or null

Booking

appointment

Fetch an appointment by ID.

query GetAppointment($id: ID!) {
  appointment(id: $id) {
    id
    service {
      id
      name
      duration
      price
    }
    staff {
      id
      name
    }
    customer {
      id
      name
      email
    }
    startTime
    endTime
    status
    notes
  }
}

Returns: Appointment or null

availability

Check staff availability for a service on a specific date.

query GetAvailability($serviceId: ID!, $date: Date!, $staffId: ID) {
  availability(serviceId: $serviceId, date: $date, staffId: $staffId) {
    date
    slots {
      time
      available
      staff {
        id
        name
      }
    }
  }
}

Arguments:

Returns: Availability

Promotions

promotion

Fetch a promotion by ID.

query GetPromotion($id: ID!) {
  promotion(id: $id) {
    id
    name
    description
    type
    discountType
    discountValue
    startDate
    endDate
    status
    conditions {
      minPurchaseAmount
      productIds
      categoryIds
    }
    usageCount
    usageLimit
  }
}

Returns: Promotion or null

validateCoupon

Validate a coupon code.

query ValidateCoupon($code: String!, $cartTotal: Money) {
  validateCoupon(code: $code, cartTotal: $cartTotal) {
    valid
    coupon {
      code
      discountType
      discountValue
    }
    discountAmount
    reason
  }
}

Arguments:

Returns: CouponValidation

Analytics

salesReport

Generate a sales report for a date range.

query GetSalesReport($startDate: Date!, $endDate: Date!) {
  salesReport(startDate: $startDate, endDate: $endDate) {
    totalRevenue
    orderCount
    averageOrderValue

    topProducts {
      product {
        id
        name
      }
      revenue
      unitsSold
    }

    revenueByDay {
      date
      revenue
      orderCount
    }

    revenueByCategory {
      category {
        id
        name
      }
      revenue
      percentage
    }
  }
}

Arguments:

Returns: SalesReport

Search

search

Full-text search across products and content.

query Search($query: String!, $filters: SearchFilters, $first: Int) {
  search(query: $query, filters: $filters, first: $first) {
    results {
      ... on Product {
        id
        name
        price
        images(limit: 1) {
          url
        }
      }
      ... on Category {
        id
        name
        slug
      }
    }
    suggestions
    facets {
      category {
        value
        count
      }
      priceRange {
        min
        max
      }
    }
    totalCount
  }
}

Arguments:

Returns: SearchResults

Merchant Account

merchantAccount

Fetch the current merchant account settings.

query GetMerchantAccount {
  merchantAccount {
    id
    name
    email
    phone
    website

    subscription {
      plan
      status
      currentPeriodEnd
    }

    settings {
      currency
      timezone
      taxRate
      shippingZones {
        name
        countries
        rate
      }
    }

    apiKeys {
      id
      name
      prefix
      createdAt
      lastUsedAt
    }
  }
}

No arguments required

Returns: MerchantAccount

Common Patterns

Nested Queries

Fetch related data in one request:

query GetOrderWithDetails {
  order(id: "ord_123") {
    id
    orderNumber

    # From Order Service
    total
    status

    # From CRM Service (federated)
    customer {
      name
      email
      totalSpent
    }

    # From Payment Service (federated)
    payment {
      status
      method
    }

    # From Product Catalog (federated)
    items {
      product {
        name
        images(limit: 1) {
          url
        }
      }
      quantity
    }
  }
}

Multiple Queries with Aliases

query GetMultipleProducts {
  featured: products(featured: true, first: 5) {
    edges {
      node {
        id
        name
        price
      }
    }
  }

  newest: products(sortBy: CREATED_AT, sortOrder: DESC, first: 5) {
    edges {
      node {
        id
        name
        price
      }
    }
  }

  popular: products(sortBy: POPULARITY, first: 5) {
    edges {
      node {
        id
        name
        price
      }
    }
  }
}

Conditional Fields with Directives

query GetProduct($id: ID!, $includeReviews: Boolean!) {
  product(id: $id) {
    id
    name
    price

    reviews(first: 10) @include(if: $includeReviews) {
      edges {
        node {
          rating
          comment
        }
      }
    }
  }
}

Next Steps

• Mutations Reference - Create, update, and delete resources
• Types Reference - Complete type definitions
• Interactive Playground - Try queries with autocomplete
• Code Examples - Copy/paste examples in your language

Need help? Check the GraphQL Basics Guide or ask in Discord!