Skip to main content

Core Concepts

This guide explains the key concepts and entities shared between Common Ground's Admin API and Client API. Understanding these common concepts will help you effectively use both APIs.

Common Concepts​

These concepts are shared between both Common Ground APIs, though with different access levels and field availability.

Items​

Items are the core product entities in Common Ground. They come in three types:

  • ReleaseItem: Music releases (vinyl records, CDs, cassettes) with artist, label, tracklist, and format information
  • ProductItem: General products with manufacturer, category, and product-specific attributes
  • BookItem: Books with author, publisher, ISBN, and book-specific metadata

Key Characteristics:

  • Items can have multiple listings (variants)
  • Items contain rich metadata in the data field
  • Items support images, descriptions, and SEO information
  • Items can be organized into collections

Listings​

Listings represent sellable variants of items:

  • Stock Management: Track quantity, availability, and stock levels
  • Pricing: Set sale prices, compare prices, and handle tax-inclusive/exclusive pricing
  • Attributes: Condition, location, supplier codes, SKU, barcode
  • Status: Control listing status (active, inactive, sold, etc.)
  • Availability: Set available dates, pre-order status, and posting dates

Pagination​

Both APIs use page-based pagination:

  • PaginationInput: Specify page number, limit, and sorting criterion
  • Pagination: Returns the current page, count of total pages, count, and hasMore flag
  • Usage: Navigate through large datasets efficiently

Filtering & Sorting​

Both APIs support filtering and sorting:

  • Filtering: Filter by stock status, type, categories, artists, labels, formats, genres, styles, price ranges, and more, depending on the operation
  • Sorting: Sort by various fields (createdAt, price, title, etc.) in ascending or descending order, depending on the operation
  • Usage: Narrow down results and organize data display

Addresses​

Address information used for shipping and billing:

  • Fields: Address lines, city, state, post code, country, geo-location
  • Types: Shipping addresses, billing addresses, pickup locations
  • Usage: Handle customer addresses, shipping calculations, and address validation

SEO​

The SEO settings take effect only when your client-facing storefront is managed by the Common Ground platform.

Search engine optimization metadata:

  • Fields: Title, description, slug, index status
  • Usage: Optimize product pages, collections, and articles for search engines
  • Applied to: Items, collections, articles, and other content

Music-Specific Concepts​

These concepts are particularly relevant for music/vinyl stores and are used in both APIs:

Tracklists​

Lists of tracks/songs for release items. Includes track titles, artists, durations, positions, and audio preview URIs.

Artists​

Musical artists or performers associated with release items. Used for browsing, filtering, and organizing products.

Labels​

Record labels that released items. Used for organizing and filtering by label.

Formats​

Physical formats of releases (e.g., "12" Vinyl", "CD", "Cassette"). Includes format details like quantity and descriptions.

Genres & Styles​

Musical genres (e.g., "Jazz", "Rock") and styles (e.g., "Bebop", "Hard Bop") for categorizing releases.

API-Specific Concepts​

Admin API Concepts​

The Admin API includes additional concepts for backend management:

  • Suppliers: Track product sources and supplier information
  • Users (Admin): Administrative users with roles and permissions
  • Access Keys: API credentials for server-to-server authentication
  • Vouchers & Credits: Discount codes and store credit management
  • Config: Complete store configuration including payment, shipping, and tax settings
  • Shipping Policies: Rules for calculating shipping costs
  • Discogs Integration: Marketplace integration for syncing and listing
  • Jobs: Background jobs for bulk operations
  • Templates: Email and document templates
  • Media Management: Upload and organize media assets
  • Audio Snippets: Upload and manage audio previews
  • Lists, Campaigns, Messages, Invoices, Notifications, Dashboard: Additional administrative features

Learn more about Admin API concepts →

Client API Concepts​

The Client API includes concepts optimized for customer-facing features:

  • Wantlist: Customer wishlist functionality
  • Search: Product search and discovery
  • Suggestions: Product recommendations based on genres, styles, or related items
  • Users (Buyer): Customer account management
  • Sessions: Customer authentication

Learn more about Client API concepts →

Next Steps​