Types Reference

Complete reference of all GraphQL types, input objects, and enums in Unified Commerce Platform.

Overview

GraphQL is strongly typed. Every field returns a specific type, and you can only query fields that exist on that type.

Type Notation

String - Nullable string (can be null)
String! - Non-nullable string (guaranteed to return a value)
[String] - Array of nullable strings (array itself can be null)
[String!] - Array of non-nullable strings (array can be null, but elements cannot)
[String!]! - Non-nullable array of non-nullable strings

Scalar Types

Built-in Scalars

Type	Description	Example
`ID`	Unique identifier (string)	`"prod_abc123"`
`String`	UTF-8 text	`"Hello World"`
`Int`	32-bit signed integer	`42`
`Float`	Double-precision floating-point	`3.14159`
`Boolean`	True or false	`true`

Custom Scalars

scalar DateTime      # ISO 8601 timestamp: "2025-01-15T10:30:00Z"
scalar Date          # ISO 8601 date: "2025-01-15"
scalar Money         # Integer in cents: 2999 = $29.99
scalar JSON          # Arbitrary JSON object
scalar URL           # Valid HTTP/HTTPS URL
scalar EmailAddress  # Valid email address

Money Type

All monetary values use Money (integer in cents) to avoid floating-point precision issues:

// Backend stores: 2999 (cents)
// Display as: $29.99

const formatMoney = (cents: number, currency: string) => {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: currency
  }).format(cents / 100);
};

Object Types

Product

Represents a product in the catalog.

type Product {
  id: ID!
  name: String!
  description: String
  sku: String!
  price: Money!
  currency: String!
  compareAtPrice: Money
  costPerItem: Money
  status: ProductStatus!

  # Images
  images: [ProductImage!]!

  # Categories
  categories: [Category!]!

  # Variants
  variants: [ProductVariant!]!
  hasVariants: Boolean!

  # Federated fields from other services
  inventory: Inventory
  orders(first: Int, after: String): OrderConnection
  reviews(first: Int): ReviewConnection

  # SEO
  seoTitle: String
  seoDescription: String
  slug: String!

  # Metadata
  tags: [String!]!
  createdAt: DateTime!
  updatedAt: DateTime!
}

ProductImage

type ProductImage {
  id: ID!
  url: URL!
  alt: String
  width: Int
  height: Int
  order: Int!
}

ProductVariant

type ProductVariant {
  id: ID!
  productId: ID!
  sku: String!
  price: Money
  compareAtPrice: Money
  options: [VariantOption!]!
  inventory: Inventory
  createdAt: DateTime!
}

VariantOption

type VariantOption {
  name: String!      # e.g., "Size", "Color"
  value: String!     # e.g., "Large", "Blue"
}

Order

type Order {
  id: ID!
  orderNumber: String!
  status: OrderStatus!

  # Pricing
  subtotal: Money!
  tax: Money!
  shipping: Money!
  discount: Money!
  total: Money!
  currency: String!

  # Items
  items: [OrderItem!]!
  itemCount: Int!

  # Customer (federated from CRM)
  customer: Customer!
  customerId: ID!

  # Addresses
  shippingAddress: Address!
  billingAddress: Address

  # Payment (federated from Payment service)
  payment: Payment

  # Fulfillment
  fulfillment: Fulfillment

  # Coupon
  coupon: Coupon

  # Metadata
  notes: String
  tags: [String!]!
  createdAt: DateTime!
  updatedAt: DateTime!
}

OrderItem

type OrderItem {
  id: ID!
  orderId: ID!

  # Product reference (federated)
  product: Product!
  productId: ID!
  variant: ProductVariant
  variantId: ID

  # Pricing
  quantity: Int!
  price: Money!      # Price at time of purchase
  subtotal: Money!

  # Snapshot of product data at purchase time
  productName: String!
  productImage: URL
}

Fulfillment

type Fulfillment {
  id: ID!
  orderId: ID!
  status: FulfillmentStatus!
  trackingNumber: String
  carrier: String
  shippedAt: DateTime
  estimatedDeliveryAt: DateTime
  deliveredAt: DateTime
}

Customer

type Customer {
  id: ID!
  email: EmailAddress!
  name: String!
  phone: String

  # Purchase history
  totalSpent: Money!
  orderCount: Int!
  averageOrderValue: Money!
  lastOrderDate: DateTime

  # Loyalty
  loyaltyPoints: Int!
  loyaltyTier: String

  # Addresses
  addresses: [Address!]!
  defaultAddress: Address

  # Orders (federated)
  orders(
    first: Int
    after: String
    filters: OrderFilters
  ): OrderConnection!

  # Preferences
  marketingOptIn: Boolean!
  emailVerified: Boolean!

  # Metadata
  tags: [String!]!
  notes: String
  createdAt: DateTime!
  updatedAt: DateTime!
}

Address

type Address {
  id: ID!
  line1: String!
  line2: String
  city: String!
  state: String!
  postalCode: String!
  country: String!
  phone: String
  isDefault: Boolean!
}

Cart

type Cart {
  id: ID!
  customerId: ID

  # Items
  items: [CartItem!]!
  itemCount: Int!

  # Pricing
  subtotal: Money!
  tax: Money!
  shipping: Money!
  discount: Money!
  total: Money!
  currency: String!

  # Coupon
  coupon: Coupon

  # Metadata
  expiresAt: DateTime!
  createdAt: DateTime!
  updatedAt: DateTime!
}

CartItem

type CartItem {
  id: ID!
  cartId: ID!

  # Product (federated)
  product: Product!
  productId: ID!
  variant: ProductVariant
  variantId: ID

  quantity: Int!
  price: Money!
  subtotal: Money!

  # Real-time inventory check
  available: Boolean!
  maxQuantity: Int
}

User

type User {
  id: ID!
  email: EmailAddress!
  name: String!
  phone: String

  # Authentication
  emailVerified: Boolean!
  mfaEnabled: Boolean!
  lastLoginAt: DateTime

  # Authorization
  roles: [Role!]!
  permissions: [String!]!

  # Status
  status: UserStatus!

  createdAt: DateTime!
  updatedAt: DateTime!
}

Role

type Role {
  id: ID!
  name: String!
  description: String
  permissions: [String!]!
}

Payment

type Payment {
  id: ID!
  orderId: ID
  amount: Money!
  currency: String!
  status: PaymentStatus!
  method: PaymentMethod!

  # Card details (for card payments)
  last4: String
  brand: String
  expiryMonth: Int
  expiryYear: Int

  # Metadata
  stripePaymentIntentId: String
  failureReason: String

  # Refunds
  refunds: [Refund!]!
  refundedAmount: Money!

  createdAt: DateTime!
  updatedAt: DateTime!
}

Refund

type Refund {
  id: ID!
  paymentId: ID!
  amount: Money!
  reason: String!
  status: RefundStatus!
  createdAt: DateTime!
}

Inventory

type Inventory {
  productId: ID!
  variantId: ID

  # Stock levels
  available: Int!
  reserved: Int!
  inTransit: Int!

  # Thresholds
  lowStockThreshold: Int!
  isLowStock: Boolean!

  # Warehouses
  warehouses: [WarehouseInventory!]!

  # History
  lastRestockedAt: DateTime
  lastSoldAt: DateTime

  updatedAt: DateTime!
}

WarehouseInventory

type WarehouseInventory {
  warehouseId: ID!
  warehouse: Warehouse!
  available: Int!
  reserved: Int!
}

Warehouse

type Warehouse {
  id: ID!
  name: String!
  code: String!
  location: Address!
  active: Boolean!
}

Appointment

type Appointment {
  id: ID!
  service: BookingService!
  serviceId: ID!
  staff: StaffMember!
  staffId: ID!
  customer: Customer!
  customerId: ID!

  startTime: DateTime!
  endTime: DateTime!
  duration: Int!        # minutes

  status: AppointmentStatus!

  notes: String
  reminderSent: Boolean!

  createdAt: DateTime!
  updatedAt: DateTime!
}

BookingService

type BookingService {
  id: ID!
  name: String!
  description: String
  duration: Int!        # minutes
  price: Money!
  currency: String!
  active: Boolean!
}

StaffMember

type StaffMember {
  id: ID!
  name: String!
  email: EmailAddress!
  phone: String
  services: [BookingService!]!
  schedule: [Schedule!]!
  active: Boolean!
}

Promotion

type Promotion {
  id: ID!
  name: String!
  description: String
  code: String

  # Discount
  discountType: DiscountType!
  discountValue: Int!

  # Validity
  startDate: DateTime!
  endDate: DateTime!
  status: PromotionStatus!

  # Usage
  usageCount: Int!
  usageLimit: Int

  # Conditions
  conditions: PromotionConditions

  createdAt: DateTime!
  updatedAt: DateTime!
}

PromotionConditions

type PromotionConditions {
  minPurchaseAmount: Money
  maxDiscountAmount: Money
  productIds: [ID!]
  categoryIds: [ID!]
  customerIds: [ID!]
  firstOrderOnly: Boolean!
}

Coupon

type Coupon {
  code: String!
  promotion: Promotion!
  promotionId: ID!
  discountAmount: Money!
  expiresAt: DateTime
}

MerchantAccount

type MerchantAccount {
  id: ID!
  name: String!
  email: EmailAddress!
  phone: String
  website: URL

  # Subscription
  subscription: Subscription!

  # Settings
  settings: MerchantSettings!

  # API Keys
  apiKeys: [ApiKey!]!

  createdAt: DateTime!
  updatedAt: DateTime!
}

Subscription

type Subscription {
  plan: SubscriptionPlan!
  status: SubscriptionStatus!
  currentPeriodStart: DateTime!
  currentPeriodEnd: DateTime!
  cancelAtPeriodEnd: Boolean!
}

MerchantSettings

type MerchantSettings {
  currency: String!
  timezone: String!
  taxRate: Float!
  shippingZones: [ShippingZone!]!
}

ApiKey

type ApiKey {
  id: ID!
  name: String!
  prefix: String!          # e.g., "uc_live_"
  permissions: [String!]!
  lastUsedAt: DateTime
  createdAt: DateTime!
}

Connection Types

Connection types follow the Relay specification for pagination.

ProductConnection

type ProductConnection {
  edges: [ProductEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type ProductEdge {
  cursor: String!
  node: Product!
}

OrderConnection

type OrderConnection {
  edges: [OrderEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type OrderEdge {
  cursor: String!
  node: Order!
}

PageInfo

Used by all connection types:

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

Input Types

CreateProductInput

input CreateProductInput {
  name: String!
  description: String
  sku: String!
  price: Money!
  currency: String!
  compareAtPrice: Money
  costPerItem: Money
  categoryIds: [ID!]
  tags: [String!]
  images: [ProductImageInput!]
  variants: [ProductVariantInput!]
  status: ProductStatus
  seoTitle: String
  seoDescription: String
}

ProductImageInput

input ProductImageInput {
  url: URL!
  alt: String
  order: Int
}

CreateOrderInput

input CreateOrderInput {
  customerId: ID!
  items: [OrderItemInput!]!
  shippingAddress: AddressInput!
  billingAddress: AddressInput
  shippingMethodId: ID
  couponCode: String
  notes: String
}

OrderItemInput

input OrderItemInput {
  productId: ID!
  variantId: ID
  quantity: Int!
}

AddressInput

input AddressInput {
  line1: String!
  line2: String
  city: String!
  state: String!
  postalCode: String!
  country: String!
  phone: String
}

ProductFilters

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

OrderFilters

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

Enum Types

ProductStatus

enum ProductStatus {
  DRAFT         # Not visible to customers
  ACTIVE        # Available for purchase
  ARCHIVED      # Hidden, no longer sold
}

OrderStatus

enum OrderStatus {
  PENDING       # Created, awaiting payment
  CONFIRMED     # Payment received
  PROCESSING    # Being prepared for shipment
  SHIPPED       # Shipped to customer
  DELIVERED     # Delivered to customer
  CANCELLED     # Cancelled by customer or merchant
  REFUNDED      # Refunded to customer
}

FulfillmentStatus

enum FulfillmentStatus {
  UNFULFILLED
  PARTIAL
  FULFILLED
  SHIPPED
  DELIVERED
  RETURNED
}

PaymentStatus

enum PaymentStatus {
  PENDING
  PROCESSING
  SUCCEEDED
  FAILED
  CANCELLED
  REFUNDED
  PARTIALLY_REFUNDED
}

PaymentMethod

enum PaymentMethod {
  CARD
  BANK_TRANSFER
  CASH
  PAYPAL
  APPLE_PAY
  GOOGLE_PAY
}

UserStatus

enum UserStatus {
  ACTIVE
  INACTIVE
  SUSPENDED
  DELETED
}

AppointmentStatus

enum AppointmentStatus {
  SCHEDULED
  CONFIRMED
  IN_PROGRESS
  COMPLETED
  CANCELLED
  NO_SHOW
}

DiscountType

enum DiscountType {
  PERCENTAGE        # e.g., 20% off
  FIXED_AMOUNT      # e.g., $10 off
  FREE_SHIPPING     # Free shipping
}

PromotionStatus

enum PromotionStatus {
  SCHEDULED         # Not yet active
  ACTIVE            # Currently active
  EXPIRED           # Past end date
  DISABLED          # Manually disabled
}

SubscriptionPlan

enum SubscriptionPlan {
  FREE
  STARTER
  PRO
  ENTERPRISE
}

SubscriptionStatus

enum SubscriptionStatus {
  ACTIVE
  TRIALING
  PAST_DUE
  CANCELLED
  UNPAID
}

SortOrder

enum SortOrder {
  ASC
  DESC
}

ProductSortField

enum ProductSortField {
  NAME
  PRICE
  CREATED_AT
  UPDATED_AT
  POPULARITY
}

OrderSortField

enum OrderSortField {
  ORDER_NUMBER
  TOTAL
  CREATED_AT
  UPDATED_AT
  STATUS
}

Union Types

SearchResult

union SearchResult = Product | Category | Article

Usage:

query Search($query: String!) {
  search(query: $query) {
    results {
      ... on Product {
        id
        name
        price
      }
      ... on Category {
        id
        name
        slug
      }
      ... on Article {
        id
        title
        excerpt
      }
    }
  }
}

Interface Types

Node

All resources implement the Node interface for global identification:

interface Node {
  id: ID!
}

type Product implements Node {
  id: ID!
  # ... other fields
}

type Order implements Node {
  id: ID!
  # ... other fields
}

Timestamped

Common timestamp fields:

interface Timestamped {
  createdAt: DateTime!
  updatedAt: DateTime!
}

Error Types

UserError

Validation and business logic errors:

type UserError {
  field: String         # Which field caused the error
  message: String!      # Human-readable message
  code: String          # Machine-readable code
}

Common Error Codes

enum ErrorCode {
  # Authentication
  UNAUTHENTICATED
  UNAUTHORIZED
  TOKEN_EXPIRED

  # Validation
  REQUIRED_FIELD
  INVALID_VALUE
  INVALID_FORMAT
  OUT_OF_RANGE

  # Business Logic
  NOT_FOUND
  ALREADY_EXISTS
  INSUFFICIENT_INVENTORY
  PAYMENT_FAILED
  INVALID_COUPON

  # System
  INTERNAL_SERVER_ERROR
  SERVICE_UNAVAILABLE
  RATE_LIMITED
}

Type Extensions (Federation)

Services extend types from other services:

# Product Catalog Service defines Product
type Product @key(fields: "id") {
  id: ID!
  name: String!
  price: Money!
}

# Inventory Service extends Product
extend type Product @key(fields: "id") {
  id: ID! @external
  inventory: Inventory
}

# Order Service extends Product
extend type Product @key(fields: "id") {
  id: ID! @external
  orders(first: Int): OrderConnection
  totalSold: Int!
}

Best Practices

1. Always Request ID Fields

IDs are needed for caching and refetching:

query {
  products {
    id        # ✅ Always include
    name
    price
  }
}

2. Use Fragments for Reusable Types

fragment AddressFields on Address {
  line1
  line2
  city
  state
  postalCode
  country
}

query {
  customer {
    shippingAddress {
      ...AddressFields
    }
    billingAddress {
      ...AddressFields
    }
  }
}

3. Request `__typename` for Unions

query {
  search(query: "shirt") {
    __typename    # ✅ Know which type it is
    ... on Product { id name }
    ... on Category { id name }
  }
}

4. Use Non-Null Types for Required Fields

When defining your own types:

type MyType {
  required: String!      # ✅ Client knows this is always present
  optional: String       # ⚠️ Client must handle null
}

Interactive Schema Explorer

Explore the complete schema interactively:

GraphQL Playground - Browse types with autocomplete
Schema Visualizer - Visual graph of type relationships

Next Steps

Queries Reference - Fetch data
Mutations Reference - Modify data
GraphQL Basics - Learn GraphQL fundamentals

Questions about types? Ask in our Discord community!