Skip to main content

Common Ground Developer Documentation Hero

Common Ground Developer Documentation

Welcome to the Common Ground Developer Documentation. This comprehensive guide will help you integrate with Common Ground's powerful GraphQL APIs to build applications that manage inventory, process orders, handle checkouts, and create engaging e-commerce experiences.

Key Features​

  • Inventory Management: Track and manage your product catalog with detailed item information, metadata, and supplier relationships
  • Order Processing: Handle orders, checkouts, and shipping with comprehensive order management capabilities
  • Collections: Organize your products into collections
  • User Management: Manage customers, accounts, and user preferences
  • Media Management: Upload, organize, and serve media assets for your products and content
  • Multi-channel Integration: Connect with external services like Discogs and other marketplaces

GraphQL APIs​

Common Ground provides two main GraphQL APIs, each designed for specific use cases:

Admin API​

The Admin API is designed for backend operations and administrative tasks. Use it to:

  • Manage your complete inventory and product catalog
  • Process and fulfill orders
  • Configure collections, themes, and templates
  • Handle user accounts and permissions
  • Access analytics and reporting data
  • Manage media assets and content

Best for: Backend services, administrative dashboards, inventory management systems, and internal tools.

Get started with Admin API →

Client API​

The Client API is optimized for frontend applications and public-facing integrations. Use it to:

  • Display product catalogs and collections
  • Handle customer checkouts
  • Retrieve order information
  • Access public configuration and settings
  • Build storefront experiences

Best for: E-commerce storefronts, mobile applications, public websites, and customer-facing integrations.

Get started with Client API →

Why GraphQL?​

Common Ground uses GraphQL to provide a flexible, efficient API experience:

  • Request Only What You Need: Fetch exactly the data your application requires, reducing payload sizes and improving performance
  • Single Endpoint: Access all your data through a single GraphQL endpoint
  • Strongly Typed: Benefit from a complete type system with introspection and schema validation
  • Real-time Capabilities: Use subscriptions for real-time updates when needed
  • Developer-Friendly: Explore the API with community GraphQL tools and comprehensive documentation

Getting Started​

Ready to start building? Here's your roadmap:

  1. GraphQL Basics: Understand how to work with GraphQL queries and mutations
  2. Choose Your API:
  3. Explore the Reference: Dive into the complete API reference documentation for detailed information about every query, mutation, and type

Core Concepts​

Before diving into the APIs, familiarize yourself with these key concepts:

  • Items: Products in your inventory with metadata, pricing, and availability information
  • Collections: Organized groups of items that can be displayed together
  • Orders: Customer purchases with shipping, payment, and fulfillment details
  • Checkouts: Shopping cart sessions that can be converted into orders
  • Themes: Customizable storefront designs and layouts (only applicable when your client-facing storefront is managed on the Common Ground platform)
  • Users: Customer and admin accounts with roles and permissions

Learn more about core concepts →

Documentation Structure​

This documentation is organized to help you find what you need quickly:

  • Introduction: Start here for an overview and getting started guide
  • GraphQL: Learn about GraphQL fundamentals, pagination, filtering, and error handling
  • Admin API: Complete reference for backend and administrative operations
  • Client API: Complete reference for frontend and customer-facing operations

Each API section includes:

  • Overview: High-level introduction and use cases
  • Quick Start: Step-by-step guide to make your first API calls
  • Guides: Articles that showcase how to implement a certain scenario
  • Reference: Complete documentation of all queries, mutations, types, and enums

Using Documentation with Large Language Models​

Each documentation page features a "Copy Page" button that copies the page content in Markdown format for use with Large Language Models.

Next Steps​