Skip to main content

Client API Overview

The Client API is a GraphQL API optimized for frontend applications and customer-facing integrations. Use it to build e-commerce storefronts, mobile applications, and public websites that interact with your Common Ground store.

Use Cases​

You can use the Client API for:

  • Product Catalog: Display products, browse inventory, search items, and showcase collections
  • Customer Accounts: User registration, login, profile management, and preferences
  • Shopping Experience: Browse products, view details, manage wantlists, and access suggestions
  • Checkout & Orders: Create checkouts, process payments, view order history, and track orders
  • Content Management: Display articles, playlists, themes, and storefront content
  • Search & Discovery: Search products, filter inventory, browse by artists/labels, and get recommendations
  • Public Data: Access public configuration, themes, collections, and store settings

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

Endpoint​

The Client API is available at:

  • Client API: https://api-client.common-ground.io/graphql

Authentication​

The Client API uses customer (buyer) authentication for protected operations.

Many operations are public and don't require authentication. Only user-specific operations (orders, profile, wantlist) require authentication of the current user.

Customer Authentication​

Sign-in the customer before using customer-facing features like viewing orders, managing profiles, and accessing wantlists.

Using Authentication Tokens​

After obtaining an authentication token from the login operation, include it in authenticated requests.

Include these headers in authenticated requests:

  • Authorization: Bearer <token> - Your authentication token (for authenticated operations)
  • CommonGround-Origin: <domain> - The store domain you're accessing (e.g., www.my-vinyl-store.com)

Rate Limits​

Client API access is limited to 200 requests per minute per IP.

Rate Limit Response Headers​

The API returns rate limit information in response headers:

  • RateLimit-Limit - Maximum requests allowed in the window
  • RateLimit-Remaining - Remaining requests in the current window
  • RateLimit-Reset - Time when the rate limit window resets

Best Practices​

  • Implement exponential backoff when you receive 429 Too Many Requests responses
  • Cache public data (inventory, collections, config) to reduce API calls
  • Use pagination for large datasets
  • Consider using inventory dumps for bulk data access

Query Complexity​

While the Client API doesn't enforce strict query complexity limits, consider the following:

  • Request Size: Request body size is limited to 5MB
  • Response Time: Complex queries with deep nesting may take longer to execute
  • Best Practices:
    • Request only the fields you need
    • Use pagination for inventory and collections
    • Avoid deeply nested queries when possible
    • Use filters to narrow down results
    • Cache public data when appropriate

Schema​

The Client API uses a comprehensive GraphQL schema optimized for frontend use:

  • Queries: Read operations for inventory, items, collections, orders, users, and more
  • Mutations: Write operations for login, registration, checkout, orders, and user management
  • Types: Rich type system for items, orders, users, checkouts, collections, and related entities
  • Input Types: Structured inputs for mutations, filters, and pagination
  • Enums: Predefined sets of values for statuses, types, and categories

You can download the complete Client API schema file for use with GraphQL tools, code generators, and IDEs:

Download Client API Schema

Schema introspection from the GraphQL endpoint is disabled. Use the downloadable schema file instead.

Next Steps​